Memento v0.3.2 Memento.Table behaviour View Source

Defines a Memento Table schema for Mnesia

Usage

You can define an Mnesia Table by calling use Memento.Table with a few options in your module.

defmodule Blog.Post do
  use Memento.Table, attributes: [:id, :title, :content]
end

Each table then must be created before you can interact with it. You can do that by calling create/2. It's usually a good idea to call this while your application is being started:

Memento.Table.create(Blog.Post)

Options

The table definition and the create/2 function both accept a keyword list specifying the options for the table:

  • attributes - A required list of atoms representing the attribute names of the records of the table. Must have at least two attributes, where the first one is the primary key.

  • type - One of :set, :ordered_set, or :bag. Default is :set. In a :set, all records have unique keys. In a :bag, several records can have the same key, but the record content is unique. If a non-unique record is stored, the old conflicting records are overwritten.

  • index - List of fields to index.

  • autoincrement - If the table is of the type :ordered_set, setting this true will automatically assign numeric values to non-nil primary keys when writing records (using Memento.Query.write/2). Will return an error if the table is not of the type :ordered_set.

The only required option is attributes. See :mnesia.create_table/2 for a full list of options. See the following example that uses more options:

defmodule Blog.Post do
  use Memento.Table,
    attributes: [:id, :title, :content, :status, :author_id],
    index: [:status, :author_id],
    type: :ordered_set,
    autoincrement: true


  # You can also define other methods
  # or helper functions in the module
end

Link to this section Summary

Types

A Memento.Table module

A Memento.Table record data struct

Table storage/copy type

Functions

Deletes all entries in the given Memento Table

Creates a Memento Table for Mnesia

Same as create/2, but raises error on failure

Makes a copy of a table at the given node

Deletes a Memento Table for Mnesia

Same as delete/1, but raises error on failure

Deletes the replica of a table on the specified node

Returns all table information

Moves a table's copy from one node to the other

Sets the storage type of a table for the specified node

Wait until specified tables are ready

Callbacks

Returns Table definition information

Link to this section Types

A Memento.Table module

A Memento.Table record data struct

Link to this type

storage_type() View Source
storage_type() :: :ram_copies | :disc_copies | :disc_only_copies

Table storage/copy type

Link to this section Functions

Link to this function

clear(table) View Source
clear(name()) :: :ok | {:error, any()}

Deletes all entries in the given Memento Table.

Returns :ok on success and {:error, reason} on failure.

Link to this function

create(table, opts \\ []) View Source
create(name(), Keyword.t()) :: :ok | {:error, any()}

Creates a Memento Table for Mnesia.

This must be called before you can interact with the table in any way. Uses the attributes specified in the table definition. Returns :ok on success or {:error, reason} on failure. Will raise an error if the passed module isn't a Memento Table.

You can optionally pass a set of options keyword, which will override all options specified in the definition except :attributes. See :mnesia.create_table/2 for all available options.

Link to this function

create!(table, opts \\ []) View Source
create!(name(), Keyword.t()) :: :ok | no_return()

Same as create/2, but raises error on failure.

Link to this function

create_copy(table, node, type) View Source
create_copy(name(), node(), storage_type()) :: :ok | {:error, any()}

Makes a copy of a table at the given node.

Especially useful when you want to replicate a table on another node on the fly, usually when connecting to it the first time.

The argument type must be a valid storage_type() atom. This can also be used to create a replica of the internal :schema table.

Also see :mnesia.add_table_copy/3.

Example

# Create an on-disc replica of `Users` table on another node
Memento.Table.create_copy(Users, :some_node@host_x, :disc_copies)
Link to this function

delete(table) View Source
delete(name()) :: :ok | {:error, any()}

Deletes a Memento Table for Mnesia.

Returns :ok on success and {:error, reason} on failure.

Link to this function

delete!(table) View Source
delete!(name()) :: :ok | no_return()

Same as delete/1, but raises error on failure.

Link to this function

delete_copy(table, node) View Source
delete_copy(name(), node()) :: :ok | {:error, any()}

Deletes the replica of a table on the specified node.

When the last replica of a table is deleted, the table disappears entirely. This function can also be used to delete the replica of the internal :schema table which will cause the Mnesia node to be removed (Mnesia/Memento must be stopped first).

Also see :mnesia.del_table_copy/2.

Link to this function

info(table, key \\ :all) View Source
info(name(), atom()) :: any()

Returns all table information.

Optionally accepts an extra atom argument key which returns result for only that key. Will throw an exception if the key is invalid. See :mnesia.table_info/2 for a full list of allowed keys.

Link to this function

move_copy(table, node_from, node_to) View Source
move_copy(name(), node(), node()) :: :ok | {:error, any()}

Moves a table's copy from one node to the other.

This operation preserves the storage type of the table. For example, a :ram_copies table when moved from one node, remains keeps its :ram_copies storage type on the new node.

Other transactions can still read and write while it's being moved. This function cannot be called on the internal :local_content tables.

Also see :mnesia.move_table_copy/3.

Link to this function

set_storage_type(table, node, type) View Source
set_storage_type(name(), node(), storage_type()) :: :ok | {:error, any()}

Sets the storage type of a table for the specified node.

Useful when you want to change the table's copy type on the fly, usually when connecting to a new, unsynchronized node on discovery at runtime.

The argument type must be a valid storage_type() atom. This can also be used for the internal :schema table, but you should use Memento.Schema.set_storage_type/2 instead.

See :mnesia.change_table_copy_type/3 for more details.

Example

Memento.Table.set_storage_type(MyTable, :node@host, :disc_copies)
Link to this function

wait(tables, timeout \\ 3000) View Source
wait([name()], integer() | :infinity) ::
  :ok | {:timeout, [name()]} | {:error, any()}

Wait until specified tables are ready.

Before performing some tasks, it's necessary that certain tables are ready and accessible. This call hangs until all tables specified are accessible, or until timeout is reached (default: 3000ms).

The timeout value can either be :infinity or an integer representing time in milliseconds. If you pass a Table/Module that does not exist along with :infinity as timeout, it will hang your process until that table is created and ready.

This method can be accessed directly on the Memento module as well.

For more information, see :mnesia.wait_for_tables/2.

Examples

# Wait until the `Movies` table is ready
Memento.Table.wait(Movies, :infinity)

# Wait a maximum of 3 seconds until the two tables are ready
Memento.wait([TableA, TableB])

Link to this section Callbacks

Link to this callback

__info__() View Source
__info__() :: map()

Returns Table definition information.

Every defined Memento.Table via the use macro, will export this method, returning information about its attributes, structure, options and other details.