Simple but Powerful Elixir interface to the Erlang Mnesia Database Mnesia. Memento. Get it?
Memento is an extremely easy-to-use and powerful wrapper in Elixir that makes it intuitive to work with
Mnesia, the Erlang Distributed Realtime Database. The original Mnesia API in Erlang is convoluted, unorganized
and combined with the complex MatchSpec
and QLC
query language, is hard to work with in Elixir, especially for
beginners. Memento attempts to define a simple API to work with schemas, removing the majority of complexity associated
with it.
Add :memento
to your list of dependencies in your Mix file:
def deps do
[{:memento, "~> 0.4.1"}]
end
If your Elixir version is 1.3
or lower, also add it to your applications
list:
def application do
[applications: [:memento]]
end
It's preferable to only add :memento
and not :mnesia
along with it. This will ensure that that OTP calls to Mnesia
go through the Supervisor spec specified in Memento.
It is highly recommended that a custom path to the Mnesia database location is specified, even on the local :dev
environment (You can add .mnesia
to your .gitignore
):
# config/config.exs
config :mnesia,
dir: '.mnesia/#{Mix.env}/#{node()}' # Notice the single quotes
You start by defining a Module as a Memento Table by specifying its attributes, type and other options. At least two
attributes are required, where the first one is the primary-key
of the table. A simple definition looks like this:
defmodule Blog.Author do
use Memento.Table, attributes: [:username, :fullname]
end
A slightly more complex definition that uses more options, could look like this:
defmodule Blog.Post do
use Memento.Table,
attributes: [:id, :title, :content, :status, :author],
index: [:status, :author],
type: :ordered_set,
autoincrement: true
# You can also define other methods
# or helper functions in the module
end
Once you have defined your schemas, you need to create them before you can interact with them:
Memento.Table.create!(Blog.Author)
Memento.Table.create!(Blog.Post)
See the Memento.Table
documentation for detailed examples and more information about all the options.
Once a Table has been created, you can perform read/write/delete operations on their records. An API for all of
these operations is exposed in the Memento.Query
module, but these methods can't be called directly.
Instead, they must always be called inside a Memento.Transaction
:
Memento.transaction! fn ->
Memento.Query.all(Blog.Author)
end
# => [
# %Blog.Author{username: :sye, fullname: "Sheharyar Naseer"},
# %Blog.Author{username: :jeanne, fullname: "Jeanne Bolding"},
# %Blog.Author{username: :pshore, fullname: "Paul Shore"},
# ]
For the sake of succinctness, transactions are ignored in most of the examples below, but they are still required. Here's a quick overview of all the basic operations:
# Get all records in a Table
Memento.Query.all(Post)
# Get a specific record by its primary key
Memento.Query.read(Post, id)
Memento.Query.read(Author, username)
# Write a record
Memento.Query.write(%Author{username: :sarah, name: "Sarah Molton"})
# Delete a record by primary key
Memento.Query.delete(Post, id)
Memento.Query.delete(Author, username)
# Delete a record by passing the full object
Memento.Query.delete_record(%Author{username: :pshore, name: "Paul Shore"})
For more complex read operations, Memento exposes a select/3
method that lets you chain
conditions using a simplified version of the Erlang MatchSpec. This is what some queries would look like for a
Movie
table:
Get all movies named "Rush":
Memento.Query.select(Movie, {:==, :title, "Rush"})
Get all movies directed by Tarantino before the year 2000:
guards = [
{:==, :director, "Quentin Tarantino"},
{:<, :year, 2000},
]
Memento.Query.select(Movie, guards)
See Query.select/3
for more information about the guard operators and detailed examples.
Setting up disk persistence in Mnesia
has always been a bit weird. It involves stopping the application, creating
schemas on disk, restarting the application and then creating the tables with certain options. Here are the steps
you need to take to do all of that:
# List of nodes where you want to persist
nodes = [ node() ]
# Create the schema
Memento.stop
Memento.Schema.create(nodes)
Memento.start
# Create your tables with disc_copies (only the ones you want persisted on disk)
Memento.Table.create!(TableA, disc_copies: nodes)
Memento.Table.create!(TableB, disc_copies: nodes)
Memento.Table.create!(TableC)
This needs to be done only once and not every time the application starts. It also makes sense to create a helper function or mix task that does this for you. You can see a sample implementation here.
In most applications, some kind of data storage mechanism is needed, but this usually means relying on some sort of external dependency or program. Memento should be used in situations when it might not always make sense in an Application to do this (e.g. the data is ephemeral, the project needs to be kept light-weight, you need a simple data store that persists across application restarts, data-code decoupling is not important etc.).
Like mentioned in the previous point, Memento/Mnesia has specific use-cases and it might not always make sense to use it. This is usually when you don't want to couple your code and database, and want to allow independent or external accesses to transformation of your data. In such circumstances, you should always prefer using some other datastore (like Redis, Postgres, etc.).
I've been a long-time user of the Amnesia
package, but with the recent releases of Elixir (1.5 & above),
the library has started to show its age. Amnesia's dependence on the the exquisite
package has caused a lot of
compilation problems, and it's complex macro-intensive structure hasn't made it easy to fix them either. The library
itself doesn't even compile in Elixir 1.7+ so I finally decided to write my own after I desperately needed to update
my Mnesia-based projects.
Memento is meant to be an extremely lightweight wrapper for Mnesia, providing a very easy set of helpers and forcing good decisions by avoiding the "dirty" methods.
Memento is a new package so there aren't many Open Source examples available. Que is another library that uses Memento for background job processing and storing the state of these Jobs. If your project uses Memento, feel free to send in a pull-request so it can be mentioned here.
This package is available as open source under the terms of the MIT License.