EctoCellar

Store changes to your models, for auditing or versioning. Inspired by paper_trail.

Documentation

This is the user guide. See also, the API reference.

Installation

If available in Hex, the package can be installed by adding ecto_cellar to your list of dependencies in mix.exs:

def deps do
  [
    {:ecto_cellar, "~> 0.3"}
  ]
end

Usage

1. Configuration.

Add ecto_cellar configure to your config.exs.

config :ecto_cellar, :default_repo, YourApp.Repo

2. Creates versions table.

You can generate migration file for EctoCeller. Let’s type mix ecto_cellar.gen. And migrate by mix ecto.migrate.

3. Stores changes to model.

Stores after a model is changed or created. These are stored as recoverable versions for the versions table.

By Repo.insert + EctoCellar.store/2.

iex> with {:ok, post} <- %Post{title: "title", views: 0} |> @repo.insert(),
...>      {:ok, _post} <- EctoCellar.store(post) do # or store!/2
...>   # do something
...> end

or

There is also a function that wraps EctoRepo.insert, update, insert_or_update and delete.

By EctoCellar.insert_store/3. （Uses EctoCellar.update_store/3 when updated.）

iex> case EctoCellar.insert_store(post) do # or update_store/3, upsert_store/3, delete_store/3
...>   {:ok, _post} -> # do_somesing
...>   error -> error
...> end

4. Gets versions and can restore it.

Uses EctoCellar.all/2 and EctoCellar.one/3, you can get past changes versions. And use it, you can restore.

iex> post = Post.find(id)
%Post{id: 1, body: "body3"...etc}

iex> post_versions = EctoCellar.all(post) # Can get all versions.
[%Post{id: 1, body: "body3"...etc}, %Post{id: 1, body: "body2"...etc}, %Post{id: 1, body: "body1"...etc}]

iex> version_1_inserted_at = ~N[2022/12/12 12:00:12]
iex> post_version1 = EctoCellar.one(post, version_1_inserted_at)
%Post{id: 1, body: "body1", inserted_at: ~N[2022/12/12 12:00:12]...etc}

iex> post_version1
iex> |> Post.changeset([])
iex> |> Repo.update() # Restored！！！

Options

The last argument of each function accepts the following options.

• repo: You can select a repo other than the one specified in Config.

For contributers

You can test locally in these steps.

1. make setup
2. mix test

Bugs and Feature requests

Feel free to open an issues or a PR to contribute to the project.