README

hex.pm version CI GitHub code size in bytes

EctoCellar

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

documentation

Documentation

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

installation

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

Usage

1-configuration

1. Configuration.

Add ecto_cellar configure to your config.exs.

config :ecto_cellar, :default_repo, YourApp.Repo

2-creates-versions-table

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

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

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

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

For contributers

You can test locally in these steps.

  1. make setup
  2. mix test

bugs-and-feature-requests

Bugs and Feature requests

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