-module(mnesia).

-moduledoc """

A distributed key-value DBMS

The following are some of the most important and attractive capabilities

provided by Mnesia:

- A relational/object hybrid data model that is suitable for telecommunications

applications.

- A DBMS query language, Query List Comprehension (QLC) as an add-on library.

- Persistence. Tables can be coherently kept on disc and in the main memory.

- Replication. Tables can be replicated at several nodes.

- Atomic transactions. A series of table manipulation operations can be grouped

into a single atomic transaction.

- Location transparency. Programs can be written without knowledge of the actual

data location.

- Extremely fast real-time data searches.

- Schema manipulation routines. The DBMS can be reconfigured at runtime without

stopping the system.

This Reference Manual describes the Mnesia API. This includes functions that

define and manipulate Mnesia tables.

All functions in this Reference Manual can be used in any combination with

queries using the list comprehension notation. For information about the query

notation, see the `m:qlc` manual page in STDLIB.

Data in Mnesia is organized as a set of tables. Each table has a name that must

be an atom. Each table is made up of Erlang records. The user is responsible for

the record definitions. Each table also has a set of properties. The following

are some of the properties that are associated with each table:

- `type`. Each table can have `set`, `ordered_set`, or `bag` semantics. Notice

that currently `ordered_set` is not supported for `disc_only_copies`.

If a table is of type `set`, each key leads to either one or zero records.

If a new item is inserted with the same key as an existing record, the old

record is overwritten. However, if a table is of type `bag`, each key can map

to several records. All records in type `bag` tables are unique, only the keys

can be duplicated.

- `record_name`. All records stored in a table must have the same name. The

records must be instances of the same record type.

- `ram_copies`. A table can be replicated on a number of Erlang nodes. Property

`ram_copies` specifies a list of Erlang nodes where RAM copies are kept. These

copies can be dumped to disc at regular intervals. However, updates to these

copies are not written to disc on a transaction basis.

- `disc_copies`. This property specifies a list of Erlang nodes where the table

is kept in RAM and on disc. All updates of the table are performed in the

actual table and are also logged to disc. If a table is of type `disc_copies`

at a certain node, the entire table is resident in RAM memory and on disc.

Each transaction performed on the table is appended to a `LOG` file and

written into the RAM table.

- `disc_only_copies`. Some, or all, table replicas can be kept on disc only.

These replicas are considerably slower than the RAM-based replicas.

- `index`. This is a list of attribute names, or integers, which specify the

tuple positions on which Mnesia is to build and maintain an extra index table.

- `local_content`. When an application requires tables whose contents are local

to each node, `local_content` tables can be used. The table name is known to

all Mnesia nodes, but its content is unique on each node. This means that

access to such a table must be done locally. Set field `local_content` to

`true` to enable the `local_content` behavior. Default is `false`.

- `majority`. This attribute is `true` or `false`; default is `false`. When

`true`, a majority of the table replicas must be available for an update to

succeed. Majority checking can be enabled on tables with mission-critical

data, where it is vital to avoid inconsistencies because of network splits.

- `snmp`. Each (set-based) Mnesia table can be automatically turned into a

Simple Network Management Protocol (SNMP) ordered table as well. This property

specifies the types of the SNMP keys.

- `attributes`. The names of the attributes for the records that are inserted in

the table.

For information about the complete set of table properties and their details,

see `mnesia:create_table/2`.

This Reference Manual uses a table of persons to illustrate various examples.

The following record definition is assumed:

-record(person, {name,

age = 0,

address = unknown,

salary = 0,

children = []}),

```

The first record attribute is the primary key, or key for short.

The function descriptions are sorted in alphabetical order. It is recommended to

start to read about `mnesia:create_table/2`, `mnesia:lock/2`, and

`mnesia:activity/4` before you continue and learn about the rest.

Writing or deleting in transaction-context creates a local copy of each modified

record during the transaction. During iteration, that is, `mnesia:foldl/4`,

`mnesia:foldr/4`, `mnesia:next/2`, `mnesia:prev/2`, and `mnesia:snmp_get_next_index/2`, Mnesia

compensates for every written or deleted record, which can reduce the

performance.

If possible, avoid writing or deleting records in the same transaction before

iterating over the table.

## Configuration Parameters

[](){: #configuration_parameters }

Mnesia reads the following application configuration parameters:

- `-mnesia access_module Module`. The name of the Mnesia activity access

callback module. Default is `mnesia`.

- `-mnesia auto_repair true | false`. This flag controls if Mnesia automatically

tries to repair files that have not been properly closed. Default is `true`.

- `-mnesia backup_module Module`. The name of the Mnesia backup callback module.

Default is `mnesia_backup`.

- `-mnesia debug Level`. Controls the debug level of Mnesia. The possible values

are as follows:

- **`none`** - No trace outputs. This is the default.

- **`verbose`** - Activates tracing of important debug events. These events

generate `{mnesia_info, Format, Args}` system events. Processes can

subscribe to these events with `mnesia:subscribe/1`. The events are always

sent to the Mnesia event handler.

- **`debug`** - Activates all events at the verbose level plus full trace of

all debug events. These debug events generate `{mnesia_info, Format, Args}`

system events. Processes can subscribe to these events with

`mnesia:subscribe/1`. The events are always sent to the Mnesia event

handler. On this debug level, the Mnesia event handler starts subscribing to

updates in the schema table.

- **`trace`** - Activates all events at the debug level. On this level, the

Mnesia event handler starts subscribing to updates on all Mnesia tables.

This level is intended only for debugging small toy systems, as many large

events can be generated.

- **`false`** - An alias for none.

- **`true`** - An alias for debug.

- `-mnesia core_dir Directory`. The name of the directory where Mnesia core

files is stored, or false. Setting it implies that also RAM-only nodes

generate a core file if a crash occurs.

- `-mnesia dc_dump_limit Number`. Controls how often `disc_copies` tables are

dumped from memory. Tables are dumped when

`filesize(Log) > (filesize(Tab)/Dc_dump_limit)`. Lower values reduce CPU

overhead but increase disk space and startup times. Default is 4.

- `-mnesia dir Directory`. The name of the directory where all Mnesia data is

stored. The directory name must be unique for the current node. Two nodes must

never share the the same Mnesia directory. The results are unpredictable.

- `-mnesia dump_disc_copies_at_startup true | false`. If set to false, this

disables the dumping of `disc_copies` tables during startup while tables are

being loaded. The default is true.

- `-mnesia dump_log_load_regulation true | false`. Controls if log dumps are to

be performed as fast as possible, or if the dumper is to do its own load

regulation. Default is `false`.

This feature is temporary and will be removed in a future release

- `-mnesia dump_log_update_in_place true | false`. Controls if log dumps are

performed on a copy of the original data file, or if the log dump is performed

on the original data file. Default is `true`

- [](){: #dump_log_write_threshold } `-mnesia dump_log_write_threshold Max`.

`Max` is an integer that specifies the maximum number of writes allowed to the

transaction log before a new dump of the log is performed. Default is `1000`

log writes.

- [](){: #dump_log_time_threshold } `-mnesia dump_log_time_threshold Max`. `Max`

is an integer that specifies the dump log interval in milliseconds. Default is

3 minutes. If a dump has not been performed within `dump_log_time_threshold`

milliseconds, a new dump is performed regardless of the number of writes

performed.

- `-mnesia event_module Module`. The name of the Mnesia event handler callback

module. Default is `mnesia_event`.

- `-mnesia extra_db_nodes Nodes` specifies a list of nodes, in addition to the

ones found in the schema, with which Mnesia is also to establish contact.

Default is `[]` (empty list).

- `-mnesia fallback_error_function {UserModule, UserFunc}`. Specifies a

user-supplied callback function, which is called if a fallback is installed

and Mnesia goes down on another node. Mnesia calls the function with one

argument, the name of the dying node, for example,

`UserModule:UserFunc(DyingNode)`. Mnesia must be restarted, otherwise the

database can be inconsistent. The default behavior is to terminate Mnesia.

- `-mnesia max_wait_for_decision Timeout`. Specifies how long Mnesia waits for

other nodes to share their knowledge about the outcome of an unclear

transaction. By default, `Timeout` is set to the atom `infinity`. This implies

that if Mnesia upon startup detects a "heavyweight transaction" whose outcome

is unclear, the local Mnesia waits until Mnesia is started on some (in the

worst case all) of the other nodes that were involved in the interrupted

transaction. This is a rare situation, but if it occurs, Mnesia does not guess

if the transaction on the other nodes was committed or terminated. Mnesia

waits until it knows the outcome and then acts accordingly.

If `Timeout` is set to an integer value in milliseconds, Mnesia forces

"heavyweight transactions" to be finished, even if the outcome of the

transaction for the moment is unclear. After `Timeout` milliseconds, Mnesia

commits or terminates the transaction and continues with the startup. This can

lead to a situation where the transaction is committed on some nodes and

terminated on other nodes. If the transaction is a schema transaction, the

inconsistency can be fatal.

- `-mnesia no_table_loaders NUMBER`. Specifies the number of parallel table

loaders during start. More loaders can be good if the network latency is high

or if many tables contain few records. Default is `2`.

- `-mnesia send_compressed Level`. Specifies the level of compression to be used

when copying a table from the local node to another one. Default is `0`.

`Level` must be an integer in the interval `[0, 9]`, where `0` means no

compression and `9` means maximum compression. Before setting it to a non-zero

value, ensure that the remote nodes understand this configuration.

- `-mnesia max_transfer_size Number`. Specifies the estimated size in bytes of a

single packet of data to be used when copying a table from the local node to

another one. Default is `64000`.

- `-mnesia schema_location Loc`. Controls where Mnesia looks for its schema.

Parameter `Loc` can be one of the following atoms:

- **`disc`** - Mandatory disc. The schema is assumed to be located in the

Mnesia directory. If the schema cannot be found, Mnesia refuses to start.

This is the old behavior.

- **`ram`** - Mandatory RAM. The schema resides in RAM only. At startup, a

tiny new schema is generated. This default schema only contains the

definition of the schema table and only resides on the local node. Since no

other nodes are found in the default schema, configuration parameter

`extra_db_nodes` must be used to let the node share its table definitions

with other nodes.

Parameter `extra_db_nodes` can also be used on disc based nodes.

- **`opt_disc`** - Optional disc. The schema can reside on disc or in RAM. If

the schema is found on disc, Mnesia starts as a disc-based node and the

storage type of the schema table is `disc_copies`. If no schema is found on

disc, Mnesia starts as a disc-less node and the storage type of the schema

table is `ram_copies`. Default value for the application parameter is

`opt_disc`.

First, the SASL application parameters are checked, then the command-line flags

are checked, and finally, the default value is chosen.

### See Also

`m:application`, `m:dets`, `m:disk_log`, `m:ets`, `m:qlc`

""".

-spec start() -> result().

start() ->

start([]).

start_() ->

{Time , Res} = timer:tc(application, start, [?APPLICATION, temporary]),

Secs = Time div 1000000,

case Res of

ok ->

verbose("Mnesia started, ~p seconds~n",[ Secs]),

ok;

{error, {already_started, mnesia}} ->

verbose("Mnesia already started, ~p seconds~n",[ Secs]),

ok;

{error, R} ->

verbose("Mnesia failed to start, ~p seconds: ~p~n",[ Secs, R]),

{error, R}

end.

-doc false.

-spec start([{Option::atom(), Value::_}]) -> result().

start(ExtraEnv) when is_list(ExtraEnv) ->

case mnesia_lib:ensure_loaded(?APPLICATION) of

ok ->

patched_start(ExtraEnv);

Error ->

Error

end;

start(ExtraEnv) ->

{error, {badarg, ExtraEnv}}.

patched_start([{Env, Val} | Tail]) when is_atom(Env) ->

case mnesia_monitor:patch_env(Env, Val) of

{error, Reason} ->

{error, Reason};

_NewVal ->

patched_start(Tail)

end;

patched_start([Head | _]) ->

{error, {bad_type, Head}};

patched_start([]) ->

start_().

-doc """

""".

-spec stop() -> 'stopped' | {'error', term()}.

stop() ->

case application:stop(?APPLICATION) of

ok -> stopped;

{error, {not_started, ?APPLICATION}} -> stopped;

Other -> Other

end.

-doc """

""".

-spec change_config(Config, Value) -> ReturnValue when

Config :: config_key(),

Value :: config_value(),

ReturnValue :: config_result().

change_config(extra_db_nodes, Ns) when is_list(Ns) ->

mnesia_controller:connect_nodes(Ns);

change_config(dc_dump_limit, N) when is_number(N), N > 0 ->

case mnesia_lib:is_running() of

yes ->

mnesia_lib:set(dc_dump_limit, N),

{ok, N};

_ ->

{error, {not_started, ?APPLICATION}}

end;

change_config(BadKey, _BadVal) ->

{error, {badarg, BadKey}}.

-doc """

""".

-spec set_debug_level(Level :: debug_level()) ->

OldLevel :: debug_level().

set_debug_level(Level) ->

mnesia_subscr:set_debug_level(Level).

-doc false.

lkill() ->

mnesia_sup:kill().

-doc false.

kill() ->

rpc:multicall(mnesia_sup, kill, []).

-doc false.

ms() ->

[

mnesia_sup,

mnesia_kernel_sup,

mnesia_checkpoint_sup,

mnesia_snmp_sup,

mnesia_ext_sup,

mnesia,

mnesia_app,

mnesia_backup,

mnesia_bup,

mnesia_checkpoint,

mnesia_controller,

mnesia_dumper,

mnesia_loader,

mnesia_frag,

mnesia_frag_hash,

mnesia_index,

mnesia_late_loader,

mnesia_lib,

mnesia_log,

mnesia_schema,

mnesia_snmp_hook,

mnesia_subscr,

mnesia_text,

mnesia_tm,

mnesia_recover,

mnesia_locker,

%% Keep these last in the list, so

%% mnesia_sup kills these last

mnesia_monitor,

mnesia_event

].

-doc """

""".

-spec abort(Reason::term()) -> no_return().

abort(Reason = {aborted, _}) ->

exit(Reason);

abort(Reason) ->

exit({aborted, Reason}).

-doc """

""".

-spec is_transaction() -> boolean().

is_transaction() ->

case get(mnesia_activity_state) of

{_, Tid, _Ts} when element(1,Tid) == tid ->

true;

_ ->

false

end.

-doc(#{equiv => transaction(Fun, [], infinity)}).

-spec transaction(Fun) -> t_result(Res) when

Fun :: fun(() -> Res).

transaction(Fun) ->

transaction(get(mnesia_activity_state), Fun, [], infinity, ?DEFAULT_ACCESS, async).

-doc(#{equiv => transaction/3}).

-spec transaction(Fun, Retries) -> t_result(Res) when

Fun :: fun(() -> Res),

Retries :: non_neg_integer() | 'infinity';

(Fun, Args::[Arg::_]) -> t_result(Res) when

Fun :: fun((...) -> Res).

transaction(Fun, Retries) when is_integer(Retries), Retries >= 0 ->

transaction(get(mnesia_activity_state), Fun, [], Retries, ?DEFAULT_ACCESS, async);

transaction(Fun, Retries) when Retries == infinity ->

transaction(get(mnesia_activity_state), Fun, [], Retries, ?DEFAULT_ACCESS, async);

transaction(Fun, Args) ->

transaction(get(mnesia_activity_state), Fun, Args, infinity, ?DEFAULT_ACCESS, async).

-doc """

""".

-spec transaction(Fun, Args, Retries) -> t_result(Res) when

Fun :: fun((...) -> Res),

Args :: [Arg::_],

Retries :: non_neg_integer() | 'infinity'.

transaction(Fun, Args, Retries) ->

transaction(get(mnesia_activity_state), Fun, Args, Retries, ?DEFAULT_ACCESS, async).

-doc(#{equiv => sync_transaction(Fun, [], infinity)}).

-spec sync_transaction(Fun) -> t_result(Res) when

Fun :: fun(() -> Res).

sync_transaction(Fun) ->

transaction(get(mnesia_activity_state), Fun, [], infinity, ?DEFAULT_ACCESS, sync).

-doc(#{equiv => sync_transaction/3}).

-spec sync_transaction(Fun, Retries) -> t_result(Res) when

Fun :: fun(() -> Res) | fun((...) -> Res),

Retries :: non_neg_integer() | 'infinity';

(Fun, Args :: [Arg::_]) -> t_result(Res) when

Fun :: fun((...) -> Res).

sync_transaction(Fun, Retries) when is_integer(Retries), Retries >= 0 ->

transaction(get(mnesia_activity_state), Fun, [], Retries, ?DEFAULT_ACCESS, sync);

sync_transaction(Fun, Retries) when Retries == infinity ->

transaction(get(mnesia_activity_state), Fun, [], Retries, ?DEFAULT_ACCESS, sync);

sync_transaction(Fun, Args) ->

transaction(get(mnesia_activity_state), Fun, Args, infinity, ?DEFAULT_ACCESS, sync).

-doc """

""".

-spec sync_transaction(Fun, [Arg::_], Retries) -> t_result(Res) when

Fun :: fun((...) -> Res),

Retries :: non_neg_integer() | 'infinity'.

sync_transaction(Fun, Args, Retries) ->

transaction(get(mnesia_activity_state), Fun, Args, Retries, ?DEFAULT_ACCESS, sync).

transaction(State, Fun, Args, Retries, Mod, Kind)

when is_function(Fun), is_list(Args), Retries == infinity, is_atom(Mod) ->

mnesia_tm:transaction(State, Fun, Args, Retries, Mod, Kind);

transaction(State, Fun, Args, Retries, Mod, Kind)

when is_function(Fun), is_list(Args), is_integer(Retries), Retries >= 0, is_atom(Mod) ->

mnesia_tm:transaction(State, Fun, Args, Retries, Mod, Kind);

transaction(_State, Fun, Args, Retries, Mod, _Kind) ->

{aborted, {badarg, Fun, Args, Retries, Mod}}.

non_transaction(State, Fun, Args, ActivityKind, Mod)

when is_function(Fun), is_list(Args), is_atom(Mod) ->

mnesia_tm:non_transaction(State, Fun, Args, ActivityKind, Mod);

non_transaction(_State, Fun, Args, _ActivityKind, _Mod) ->

{aborted, {badarg, Fun, Args}}.

-doc(#{equiv => async_dirty(Fun, [])}).

-spec async_dirty(Fun) -> Res | no_return() when

Fun :: fun(() -> Res).

async_dirty(Fun) ->

async_dirty(Fun, []).

-doc """

""".

-spec async_dirty(Fun, [Arg::_]) -> Res | no_return() when

Fun :: fun((...) -> Res).

async_dirty(Fun, Args) ->

non_transaction(get(mnesia_activity_state), Fun, Args, async_dirty, ?DEFAULT_ACCESS).

-doc(#{equiv => sync_dirty/2}).

-spec sync_dirty(Fun) -> Res | no_return() when

Fun :: fun(() -> Res).

sync_dirty(Fun) ->

sync_dirty(Fun, []).

-doc """