Memento v0.3.2

View Source Memento.Table behaviour (Memento v0.3.2)

Defines a Memento Table schema for Mnesia

usage

 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

 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

name()

A Memento.Table module

record()

A Memento.Table record data struct

storage_type()

Table storage/copy type

Callbacks

__info__()

Returns Table definition information.

Functions

clear(table)

Deletes all entries in the given Memento Table.

create(table, opts \\ [])

Creates a Memento Table for Mnesia.

create!(table, opts \\ [])

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

create_copy(table, node, type)

Makes a copy of a table at the given node.

delete(table)

Deletes a Memento Table for Mnesia.

delete!(table)

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

delete_copy(table, node)

Deletes the replica of a table on the specified node.

info(table, key \\ :all)

Returns all table information.

move_copy(table, node_from, node_to)

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

set_storage_type(table, node, type)

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

wait(tables, timeout \\ 3000)

Wait until specified tables are ready.

Link to this section Types

Link to this type

name()

View Source

Specs

name() :: module()

A Memento.Table module

Link to this type

record()

View Source

Specs

record() :: struct()

A Memento.Table record data struct

Link to this type

storage_type()

View Source

Specs

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

Table storage/copy type

Link to this section Callbacks

Link to this callback

__info__()

View Source

Specs

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

Link to this section Functions

Link to this function

clear(table)

View Source

Specs

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

Specs

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

Specs

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

Specs

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

 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

Specs

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

Specs

delete!(name()) :: :ok | no_return()

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

Link to this function

delete_copy(table, node)

View Source

Specs

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

Specs

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

Specs

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

Specs

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

 Example 

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

wait(tables, timeout \\ 3000)

View Source

Specs

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

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