GSMLG.Mnesia.Table behaviour (GSMLG.Mnesia v0.1.0)

Defines a GSMLG.Mnesia Table schema for Mnesia

usage

Usage

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

defmodule Blog.Post do
  use GSMLG.Mnesia.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:

GSMLG.Mnesia.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 GSMLG.Mnesia.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 GSMLG.Mnesia.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 GSMLG.Mnesia.Table module

A GSMLG.Mnesia.Table record data struct

Table storage/copy type

Callbacks

Returns Table definition information.

Functions

Deletes all entries in the given GSMLG.Mnesia Table.

Creates a GSMLG.Mnesia Table for Mnesia.

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

Makes a copy of a table at the given node.

Deletes a GSMLG.Mnesia 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.

Link to this section Types

@type name() :: module()

A GSMLG.Mnesia.Table module

@type record() :: struct()

A GSMLG.Mnesia.Table record data struct

Link to this type

storage_type()

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

Table storage/copy type

Link to this section Callbacks

@callback __info__() :: map()

Returns Table definition information.

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

Link to this section Functions

@spec clear(name()) :: :ok | {:error, any()}

Deletes all entries in the given GSMLG.Mnesia Table.

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

Link to this function

create(table, opts \\ [])

@spec create(name(), Keyword.t()) :: :ok | {:error, any()}

Creates a GSMLG.Mnesia 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 GSMLG.Mnesia 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 \\ [])

@spec 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)

@spec 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
GSMLG.Mnesia.Table.create_copy(Users, :some_node@host_x, :disc_copies)
@spec delete(name()) :: :ok | {:error, any()}

Deletes a GSMLG.Mnesia Table for Mnesia.

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

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

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

Link to this function

delete_copy(table, node)

@spec 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/GSMLG.Mnesia must be stopped first).

Also see :mnesia.del_table_copy/2.

Link to this function

info(table, key \\ :all)

@spec 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)

@spec 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)

@spec 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 GSMLG.Mnesia.Schema.set_storage_type/2 instead.

See :mnesia.change_table_copy_type/3 for more details.

example

Example

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

transform(table, transform_fun, new_attrs)

@spec transform(module(), (... -> any()), [atom()]) ::
  {atom(), :ok} | {:aborted, term()}

Transform Table schema

For more information, see :mnesia.transform_table/3.

examples

Examples

# Transform table's schema, add attribute `imdb`
GSMLG.Mnesia.Table.transform(Movies, fn({Movies, id, name, year}) ->
  {Movies, id, name, year, nil}
end, [:id, :name, :year, :imdb])
Link to this function

wait(tables, timeout \\ 3000)

@spec 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 GSMLG.Mnesia module as well.

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

examples

Examples

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

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