RevisionairEcto
A Revisionair adapter based on Ecto. Allows you to persist and keep track of revisions of your data structures in any of Ecto's supported databases.
The things that you want to keep track of do not necessarily need to be (Ecto-backed) models/schemas. Any data structure can be used (even things that are not structs).
Installation
First, install the library by adding revisionair_ecto to your list of dependencies in mix.exs:
def deps do
[{:revisionair_ecto, "~> 1.0"}]
endThen, create a migration (mix ecto.gen.migration revisions_table) akin to the following:
defmodule RevisionairEcto.Repo.Migrations.RevisionsTable do
use Ecto.Migration
def change do
create table(:revisions, primary_key: false) do
add :item_type, :string, null: false
# If you want to use UUIDs instead, alter the following line to
# add :item_id, :uuid, null: false
add :item_id, :integer, null: false
# If you want to use JSON serialization instead, alter the following line to
# add :encoded_item, :json, null: false
add :encoded_item, :binary, null: false
add :metadata, :map, null: false
add :revision, :integer, null: false
end
create unique_index(:revisions, [:item_type, :item_id, :revision])
end
endFinally, in your config/config.exs, add the following lines to configure Revisonair and RevisionairEcto:
# Set default Revisionair storage adapter.
config :revisionair, storage: RevisionairEcto
# Default repo used by RevisionairEcto:
config :revisionair_ecto, repo: RevisionairEcto.Repo
# Uncomment if you use UUIDs instead of numerical ids:
# config :revisionair_ecto, item_id_type: :uuid
# Uncomment if you use JSON serialization instead of binary term storage:
# config :revisionair_ecto, serialization_format: :json
# Uncomment if you use a different table than "revisions" to store the revisions information:
# config :revisionair_ecto, revisions_table: "table_name"Of course, any of these settings can also be specified in the options parameter when calling any of the Revisionair functions:
Revisionair.store_revision(my_post, [storage: RevisionairEcto, storage_options: [repo: MyOtherRepo, revisions_table: "my_revisions", item_id_type: :uuid, serialization_format: :json]])(This also allows overriding certain settings only in certain special locations.)
Usage
The functions in this module should not be used directly, rather, the functions that the Revisionair module exposes should be used.
As these function calls will hit the database directly, make sure that especially store_revision is used within a Repo transaction to ensure that the revision is only stored if the other database operations could be performed successfully.
Example:
{:ok, post} = Repo.transaction fn ->
post = Repo.insert!(%Post{title: "Test", content: "Lorem ipsum"})
:ok = Revisionair.store_revision(post, Post, post.id)
# if using JSON serialization, you must also pass a whitelist of attributes you wish to serialize:
# :ok = Revisionair.store_revision(post, Post, post.id, [storage_options: [attributes: [:id, :content, :title]]])
post
end
Revisionair.newest_revision(post)
Revisionair.list_revisions(post)
Revisionair.get_revision(post, 0)Changelog
- 1.2.2 Removes unused
struct_namecolumn from migration examples. - 1.2.1 Updates migration examples (in README and tests) to no longer include unneccesary primary key and superfluous index.
- 1.2.0 Adds the possibility to serialize data using a JSON format instead of the Erlang Term Format.
- 1.1.0 Upgrade to Ecto 3.
- 1.0.2 Removes superfluous and noisy logging call.
- 1.0.1 Updates Revisionair version.
- 1.0.0 First Stable Version.