Skip to content

Latest commit

 

History

History
379 lines (256 loc) · 11.6 KB

README.md

File metadata and controls

379 lines (256 loc) · 11.6 KB
Raw

CI Status Coverage Version Version License

Simple but Powerful Elixir interface to the Erlang Mnesia Database
Mnesia. Memento. Get it?


  • 😀 Easy to Use: Provides a simple & intuitive API for working with Mnesia
  • ⚡️ Real-time: Has extremely fast real-time data searches, even across many nodes
  • 💪 Powerful Queries: on top of Erlang's MatchSpec and QLC, that are much easier to use
  • 📓 Detailed Documentation: and examples for all methods on HexDocs
  • 💾 Persistent: Schema can be coherently kept on disc & in memory
  • 🌐 Distributed: Data can easily be replicated on several nodes
  • 🌀 Atomic: A series of operations can be grouped in to a single atomic transaction
  • 🔍 Focused: Encourages good patterns by omitting dirty calls to the database
  • 🔧 Mnesia Compatible: You can still use Mnesia methods for Schemas and Tables created by Memento
  • ❄️ No Dependencies: Zero external dependencies; only uses the built-in Mnesia module
  • ⛅️ MIT Licensed: Free for personal and commercial use

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.


Installation

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.


Configuration

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

Usage

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.


CRUD Operations & Queries

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.


Persisting to Disk

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.


Roadmap

  • Memento
    • start/stop
    • info
    • system_info
    • Application
    • Config Vars
  • Memento.Table
    • Create/Delete helpers
    • clear_table
    • table_info
    • wait
    • Ecto-like DSL
    • Migration Support
  • Memento.Query
    • Integration with Memento.Table
    • match/select
    • read/write/delete
    • first/next/prev/all_keys
    • test matchspec
    • continue/1 for select continuations
    • autoincrement
    • Helper use macro
  • Memento.Transaction
    • Simple/Synchronous
    • Bang versions
    • inside?
    • abort
    • Lock Helpers
  • Memento.Schema
    • create/delete
    • print (schema/1)
  • Memento.Collection
    • Easy Helpers
    • Custom DSL
  • Mix Tasks

FAQ

1. Why Memento/Mnesia?

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.).

2. When shouldn't I use Memento/Mnesia?

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.).

3. Isn't there already an 'Amnesia' library?

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.

4. Are there any other projects that are using Memento?

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.


Contributing

  • Fork, Enhance, Send PR
  • Lock issues with any bugs or feature requests
  • Implement something from Roadmap
  • Spread the word ❤️

License

This package is available as open source under the terms of the MIT License.