1mnesia(3)                  Erlang Module Definition                  mnesia(3)
2
3
4

NAME

6       mnesia - A distributed telecommunications DBMS
7

DESCRIPTION

9       The  following  are some of the most important and attractive capabili‐
10       ties provided by Mnesia:
11
12         * A relational/object hybrid data model that is suitable for telecom‐
13           munications applications.
14
15         * A  DBMS query language, Query List Comprehension (QLC) as an add-on
16           library.
17
18         * Persistence. Tables can be coherently kept on disc and in the  main
19           memory.
20
21         * Replication. Tables can be replicated at several nodes.
22
23         * Atomic  transactions. A series of table manipulation operations can
24           be grouped into a single atomic transaction.
25
26         * Location transparency. Programs can be written without knowledge of
27           the actual data location.
28
29         * Extremely fast real-time data searches.
30
31         * Schema  manipulation routines. The DBMS can be reconfigured at run‐
32           time without stopping the system.
33
34       This Reference Manual describes the Mnesia API. This includes functions
35       that define and manipulate Mnesia tables.
36
37       All  functions  in this Reference Manual can be used in any combination
38       with queries using the list  comprehension  notation.  For  information
39       about the query notation, see the qlc manual page in STDLIB.
40
41       Data  in  Mnesia is organized as a set of tables. Each table has a name
42       that must be an atom. Each table is made up of Erlang records. The user
43       is responsible for the record definitions. Each table also has a set of
44       properties. The following are some of the properties that  are  associ‐
45       ated with each table:
46
47         * type.  Each  table  can  have  set,  ordered_set, or bag semantics.
48           Notice  that   currently   ordered_set   is   not   supported   for
49           disc_only_copies.
50
51           If  a  table  is  of type set, each key leads to either one or zero
52           records.
53
54           If a new item is inserted with the same key as an existing  record,
55           the  old record is overwritten. However, if a table is of type bag,
56           each key can map to several records. All records in type bag tables
57           are unique, only the keys can be duplicated.
58
59         * record_name. All records stored in a table must have the same name.
60           The records must be instances of the same record type.
61
62         * ram_copies. A table can be replicated on a number of Erlang  nodes.
63           Property  ram_copies  specifies  a  list  of Erlang nodes where RAM
64           copies are kept. These copies can be  dumped  to  disc  at  regular
65           intervals. However, updates to these copies are not written to disc
66           on a transaction basis.
67
68         * disc_copies. This property specifies a list of Erlang  nodes  where
69           the  table is kept in RAM and on disc. All updates of the table are
70           performed in the actual table and are also logged to disc. If a ta‐
71           ble  is  of type disc_copies at a certain node, the entire table is
72           resident in RAM memory and on disc. Each transaction  performed  on
73           the table is appended to a LOG file and written into the RAM table.
74
75         * disc_only_copies.  Some, or all, table replicas can be kept on disc
76           only. These replicas are considerably  slower  than  the  RAM-based
77           replicas.
78
79         * index.  This is a list of attribute names, or integers, which spec‐
80           ify the tuple positions on which Mnesia is to build and maintain an
81           extra index table.
82
83         * local_content.  When  an application requires tables whose contents
84           are local to each node, local_content tables can be used. The table
85           name  is  known  to  all Mnesia nodes, but its content is unique on
86           each node. This means that access to such  a  table  must  be  done
87           locally.  Set  field local_content to true to enable the local_con‐
88           tent behavior. Default is false.
89
90         * majority. This attribute is true or false; default is  false.  When
91           true,  a  majority  of  the table replicas must be available for an
92           update to succeed. Majority checking can be enabled on tables  with
93           mission-critical  data,  where it is vital to avoid inconsistencies
94           because of network splits.
95
96         * snmp. Each (set-based) Mnesia table  can  be  automatically  turned
97           into  a  Simple Network Management Protocol (SNMP) ordered table as
98           well. This property specifies the types of the SNMP keys.
99
100         * attributes. The names of the attributes for the  records  that  are
101           inserted in the table.
102
103       For  information  about  the complete set of table properties and their
104       details, see mnesia:create_table/2.
105
106       This Reference Manual uses a table of  persons  to  illustrate  various
107       examples. The following record definition is assumed:
108
109       -record(person, {name,
110                        age = 0,
111                        address = unknown,
112                        salary = 0,
113                        children = []}),
114
115       The first record attribute is the primary key, or key for short.
116
117       The  function descriptions are sorted in alphabetical order. It is rec‐
118       ommended to start to read about  mnesia:create_table/2,  mnesia:lock/2,
119       and mnesia:activity/4 before you continue and learn about the rest.
120
121       Writing or deleting in transaction-context creates a local copy of each
122       modified record during the transaction. During iteration, that is, mne‐
123       sia:fold[lr]/4,      mnesia:next/2,     mnesia:prev/2,     and     mne‐
124       sia:snmp_get_next_index/2, Mnesia  compensates  for  every  written  or
125       deleted record, which can reduce the performance.
126
127       If  possible, avoid writing or deleting records in the same transaction
128       before iterating over the table.
129

EXPORTS

131       abort(Reason) -> transaction abort
132
133              Makes the transaction silently return the tuple  {aborted,  Rea‐
134              son}.  Termination  of a Mnesia transaction means that an excep‐
135              tion is thrown to an enclosing catch. Thus, the expression catch
136              mnesia:abort(x) does not terminate the transaction.
137
138       activate_checkpoint(Args) -> {ok,Name,Nodes} | {error,Reason}
139
140              A  checkpoint  is  a consistent view of the system. A checkpoint
141              can be activated on a set of tables. This checkpoint can then be
142              traversed and presents a view of the system as it existed at the
143              time when the checkpoint was activated, even if the  tables  are
144              being or have been manipulated.
145
146              Args is a list of the following tuples:
147
148                * {name,Name}.  Name  is  the checkpoint name. Each checkpoint
149                  must have a name that is unique to the associated nodes. The
150                  name can be reused only once the checkpoint has been deacti‐
151                  vated. By default, a name that is probably unique is  gener‐
152                  ated.
153
154                * {max,MaxTabs}.  MaxTabs  is  a list of tables that are to be
155                  included in the checkpoint. Default is []. For these tables,
156                  the  redundancy  is  maximized and checkpoint information is
157                  retained together with all replicas. The checkpoint  becomes
158                  more  fault  tolerant  if  the tables have several replicas.
159                  When a new replica is added by the schema manipulation func‐
160                  tion  mnesia:add_table_copy/3,  a  retainer is also attached
161                  automatically.
162
163                * {min,MinTabs}. MinTabs is a list of tables that  are  to  be
164                  included in the checkpoint. Default is []. For these tables,
165                  the redundancy is minimized and the  checkpoint  information
166                  is  only  retained with one replica, preferably on the local
167                  node.
168
169                * {allow_remote,Bool}. false means that all retainers must  be
170                  local.  The  checkpoint  cannot be activated if a table does
171                  not reside locally. true allows retainers to be allocated on
172                  any node. Default is true.
173
174                * {ram_overrides_dump,Bool}.  Only  applicable for ram_copies.
175                  Bool allows you to choose to back up the table state  as  it
176                  is  in  RAM, or as it is on disc. true means that the latest
177                  committed records in RAM are to be included  in  the  check‐
178                  point.  These are the records that the application accesses.
179                  false means that the records dumped to DAT files are  to  be
180                  included  in  the  checkpoint.  These  records are loaded at
181                  startup. Default is false.
182
183              Returns {ok,Name,Nodes} or {error,Reason}. Name is the (possibly
184              generated)  checkpoint  name.  Nodes  are  the  nodes  that  are
185              involved in the checkpoint. Only nodes that  keep  a  checkpoint
186              retainer know about the checkpoint.
187
188       activity(AccessContext, Fun [, Args]) -> ResultOfFun | exit(Reason)
189
190              Calls   mnesia:activity(AccessContext,  Fun,  Args,  AccessMod),
191              where AccessMod is the default access callback  module  obtained
192              by mnesia:system_info(access_module). Args defaults to [] (empty
193              list).
194
195       activity(AccessContext,  Fun,  Args,  AccessMod)   ->   ResultOfFun   |
196       exit(Reason)
197
198              Executes the functional object Fun with argument Args.
199
200              The  code  that  executes  inside  the activity can consist of a
201              series of table manipulation functions, which are  performed  in
202              an  AccessContext.  Currently, the following access contexts are
203              supported:
204
205                transaction:
206                  Short for {transaction, infinity}
207
208                {transaction, Retries}:
209                  Calls mnesia:transaction(Fun, Args,  Retries).  Notice  that
210                  the  result  from Fun is returned if the transaction is suc‐
211                  cessful (atomic), otherwise the function exits with an abort
212                  reason.
213
214                sync_transaction:
215                  Short for {sync_transaction, infinity}
216
217                {sync_transaction, Retries}:
218                  Calls  mnesia:sync_transaction(Fun,  Args,  Retries). Notice
219                  that the result from Fun is returned if the  transaction  is
220                  successful  (atomic),  otherwise  the function exits with an
221                  abort reason.
222
223                async_dirty:
224                  Calls mnesia:async_dirty(Fun, Args).
225
226                sync_dirty:
227                  Calls mnesia:sync_dirty(Fun, Args).
228
229                ets:
230                  Calls mnesia:ets(Fun, Args).
231
232              This function (mnesia:activity/4) differs in  an  important  way
233              from  the functions mnesia:transaction, mnesia:sync_transaction,
234              mnesia:async_dirty, mnesia:sync_dirty, and mnesia:ets.  Argument
235              AccessMod is the name of a callback module, which implements the
236              mnesia_access behavior.
237
238              Mnesia forwards calls to the following functions:
239
240                * mnesia:lock/2 (read_lock_table/1, write_lock_table/1)
241
242                * mnesia:write/3 (write/1, s_write/1)
243
244                * mnesia:delete/3 (delete/1, s_delete/1)
245
246                * mnesia:delete_object/3 (delete_object/1, s_delete_object/1)
247
248                * mnesia:read/3 (read/1, wread/1)
249
250                * mnesia:match_object/3 (match_object/1)
251
252                * mnesia:all_keys/1
253
254                * mnesia:first/1
255
256                * mnesia:last/1
257
258                * mnesia:prev/2
259
260                * mnesia:next/2
261
262                * mnesia:index_match_object/4 (index_match_object/2)
263
264                * mnesia:index_read/3
265
266                * mnesia:table_info/2
267
268              to the corresponding:
269
270                * AccessMod:lock(ActivityId, Opaque, LockItem, LockKind)
271
272                * AccessMod:write(ActivityId, Opaque, Tab, Rec, LockKind)
273
274                * AccessMod:delete(ActivityId, Opaque, Tab, Key, LockKind)
275
276                * AccessMod:delete_object(ActivityId,  Opaque,   Tab,   RecXS,
277                  LockKind)
278
279                * AccessMod:read(ActivityId, Opaque, Tab, Key, LockKind)
280
281                * AccessMod:match_object(ActivityId,   Opaque,  Tab,  Pattern,
282                  LockKind)
283
284                * AccessMod:all_keys(ActivityId, Opaque, Tab, LockKind)
285
286                * AccessMod:first(ActivityId, Opaque, Tab)
287
288                * AccessMod:last(ActivityId, Opaque, Tab)
289
290                * AccessMod:prev(ActivityId, Opaque, Tab, Key)
291
292                * AccessMod:next(ActivityId, Opaque, Tab, Key)
293
294                * AccessMod:index_match_object(ActivityId, Opaque,  Tab,  Pat‐
295                  tern, Attr, LockKind)
296
297                * AccessMod:index_read(ActivityId,  Opaque, Tab, SecondaryKey,
298                  Attr, LockKind)
299
300                * AccessMod:table_info(ActivityId, Opaque, Tab, InfoItem)
301
302              ActivityId is a record  that  represents  the  identity  of  the
303              enclosing  Mnesia  activity. The first field (obtained with ele‐
304              ment(1, ActivityId)) contains an atom, which can be  interpreted
305              as  the activity type: ets, async_dirty, sync_dirty, or tid. tid
306              means that the activity is a transaction. The structure  of  the
307              rest of the identity record is internal to Mnesia.
308
309              Opaque is an opaque data structure that is internal to Mnesia.
310
311       add_table_copy(Tab, Node, Type) -> {aborted, R} | {atomic, ok}
312
313              Makes  another  copy  of a table at the node Node. Argument Type
314              must  be  either  of  the  atoms  ram_copies,  disc_copies,   or
315              disc_only_copies. For example, the following call ensures that a
316              disc replica of the person table also exists at node Node:
317
318              mnesia:add_table_copy(person, Node, disc_copies)
319
320              This function can also be used to add a  replica  of  the  table
321              named schema.
322
323       add_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}
324
325              Table  indexes  can  be used whenever the user wants to use fre‐
326              quently some other field than the key field to look up  records.
327              If  this  other field has an associated index, these lookups can
328              occur in constant time and space. For example, if your  applica‐
329              tion  wishes  to  use  field age to find efficiently all persons
330              with a specific age, it can be a good idea to have an  index  on
331              field age. This can be done with the following call:
332
333              mnesia:add_table_index(person, age)
334
335              Indexes  do not come for free. They occupy space that is propor‐
336              tional to the table size, and they cause insertions into the ta‐
337              ble to execute slightly slower.
338
339       all_keys(Tab) -> KeyList | transaction abort
340
341              Returns a list of all keys in the table named Tab. The semantics
342              of this function is context-sensitive. For more information, see
343              mnesia:activity/4.  In  transaction-context,  it acquires a read
344              lock on the entire table.
345
346       async_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason)
347
348              Calls the Fun in a context that is not protected by  a  transac‐
349              tion.  The Mnesia function calls performed in the Fun are mapped
350              to the corresponding dirty functions. This still  involves  log‐
351              ging,  replication,  and subscriptions, but there is no locking,
352              local transaction storage, or commit protocols involved.  Check‐
353              point  retainers  and  indexes are updated, but they are updated
354              dirty. As for normal mnesia:dirty_* operations,  the  operations
355              are   performed   semi-asynchronously.  For  details,  see  mne‐
356              sia:activity/4 and the User's Guide.
357
358              The Mnesia tables can be manipulated without using transactions.
359              This has some serious disadvantages, but is considerably faster,
360              as the transaction manager is not involved and no locks are set.
361              A  dirty  operation  does, however, guarantee a certain level of
362              consistency, and the  dirty  operations  cannot  return  garbled
363              records.  All  dirty operations provide location transparency to
364              the programmer, and a program does not have to be aware  of  the
365              whereabouts of a certain table to function.
366
367              Notice  that  it  is  more than ten times more efficient to read
368              records dirty than within a transaction.
369
370              Depending on the application, it can be a good idea to  use  the
371              dirty  functions for certain operations. Almost all Mnesia func‐
372              tions that can be called within transactions have a dirty equiv‐
373              alent, which is much more efficient.
374
375              However,  notice  that  there is a risk that the database can be
376              left in an inconsistent state if dirty operations  are  used  to
377              update  it. Dirty operations are only to be used for performance
378              reasons when it is absolutely necessary.
379
380              Notice that  calling  (nesting)  mnesia:[a]sync_dirty  inside  a
381              transaction-context inherits the transaction semantics.
382
383       backup(Opaque [, BackupMod]) -> ok | {error,Reason}
384
385              Activates a new checkpoint covering all Mnesia tables, including
386              the schema, with maximum degree of redundancy,  and  performs  a
387              backup  using  backup_checkpoint/2/3.  The  default value of the
388              backup callback module  BackupMod  is  obtained  by  mnesia:sys‐
389              tem_info(backup_module).
390
391       backup_checkpoint(Name, Opaque [, BackupMod]) -> ok | {error,Reason}
392
393              The  tables  are backed up to external media using backup module
394              BackupMod. Tables with the local contents property are backed up
395              as  they  exist  on  the  current node. BackupMod is the default
396              backup    callback    module     obtained     by     mnesia:sys‐
397              tem_info(backup_module).  For  information about the exact call‐
398              back interface (the  mnesia_backup  behavior),  see  the  User's
399              Guide.
400
401       change_config(Config, Value) -> {error, Reason} | {ok, ReturnValue}
402
403              Config  is  to be an atom of the following configuration parame‐
404              ters:
405
406                extra_db_nodes:
407                  Value is a list of nodes that Mnesia is to  try  to  connect
408                  to.  ReturnValue is those nodes in Value that Mnesia is con‐
409                  nected to.
410
411                  Notice that this function must only be used  to  connect  to
412                  newly  started  RAM nodes (N.D.R.S.N.) with an empty schema.
413                  If, for example, this function is used after the network has
414                  been partitioned, it can lead to inconsistent tables.
415
416                  Notice  that  Mnesia  can  be  connected to other nodes than
417                  those returned in ReturnValue.
418
419                dc_dump_limit:
420                  Value is a number. See the description in Section Configura‐
421                  tion  Parameters.  ReturnValue is the new value. Notice that
422                  this configuration parameter is not persistent. It  is  lost
423                  when Mnesia has stopped.
424
425       change_table_access_mode(Tab,  AccessMode)  ->  {aborted, R} | {atomic,
426       ok}
427
428              AcccessMode is by default the atom read_write but it can also be
429              set  to  the  atom read_only. If AccessMode is set to read_only,
430              updates to the table cannot be  performed.  At  startup,  Mnesia
431              always  loads read_only tables locally regardless of when and if
432              Mnesia is terminated on other nodes.
433
434       change_table_copy_type(Tab, Node, To) -> {aborted, R} | {atomic, ok}
435
436              For example:
437
438              mnesia:change_table_copy_type(person, node(), disc_copies)
439
440              Transforms the person table from a RAM table into  a  disc-based
441              table at Node.
442
443              This function can also be used to change the storage type of the
444              table named schema. The schema table can only have ram_copies or
445              disc_copies  as  the  storage  type.  If the storage type of the
446              schema is ram_copies, no other table  can  be  disc-resident  on
447              that node.
448
449       change_table_load_order(Tab, LoadOrder) -> {aborted, R} | {atomic, ok}
450
451              The  LoadOrder priority is by default 0 (zero) but can be set to
452              any integer. The tables with the highest LoadOrder priority  are
453              loaded first at startup.
454
455       change_table_majority(Tab, Majority) -> {aborted, R} | {atomic, ok}
456
457              Majority  must  be  a  boolean.  Default  is false. When true, a
458              majority of the table replicas must be available for  an  update
459              to succeed. When used on fragmented tables, Tab must be the base
460              table name. Directly changing the majority setting on individual
461              fragments is not allowed.
462
463       clear_table(Tab) -> {aborted, R} | {atomic, ok}
464
465              Deletes all entries in the table Tab.
466
467       create_schema(DiscNodes) -> ok | {error,Reason}
468
469              Creates a new database on disc. Various files are created in the
470              local Mnesia directory of each node. Notice that  the  directory
471              must  be  unique  for  each node. Two nodes must never share the
472              same directory. If possible, use a local disc device to  improve
473              performance.
474
475              mnesia:create_schema/1 fails if any of the Erlang nodes given as
476              DiscNodes are not alive, if Mnesia is  running  on  any  of  the
477              nodes,  or  if  any of the nodes already have a schema. Use mne‐
478              sia:delete_schema/1 to get rid of old faulty schemas.
479
480              Notice that only nodes with disc are to be  included  in  DiscN‐
481              odes. Disc-less nodes, that is, nodes where all tables including
482              the schema only resides in RAM, must not be included.
483
484       create_table(Name, TabDef) -> {atomic, ok} | {aborted, Reason}
485
486              Creates a Mnesia table called Name according to argument TabDef.
487              This list must be a list of {Item, Value} tuples, where the fol‐
488              lowing values are allowed:
489
490                * {access_mode, Atom}. The access mode is by default the  atom
491                  read_write  but it can also be set to the atom read_only. If
492                  AccessMode is set to read_only, updates to the table  cannot
493                  be performed.
494
495                  At  startup,  Mnesia  always  loads  read_only table locally
496                  regardless of when and if  Mnesia  is  terminated  on  other
497                  nodes.  This  argument returns the access mode of the table.
498                  The access mode can be read_only or read_write.
499
500                * {attributes, AtomList} is a list of the attribute names  for
501                  the records that are supposed to populate the table. Default
502                  is [key, val]. The  table  must  at  least  have  one  extra
503                  attribute in addition to the key.
504
505                  When accessing single attributes in a record, it is not nec‐
506                  essary, or even recommended,  to  hard  code  any  attribute
507                  names  as  atoms.  Use construct record_info(fields, Record‐
508                  Name) instead. It can be used for records  of  type  Record‐
509                  Name.
510
511                * {disc_copies,  Nodelist},  where  Nodelist  is a list of the
512                  nodes where this table is supposed to have disc copies. If a
513                  table  replica  is of type disc_copies, all write operations
514                  on this particular replica of the table are written to  disc
515                  and to the RAM copy of the table.
516
517                  It   is   possible  to  have  a  replicated  table  of  type
518                  disc_copies on one node and another type  on  another  node.
519                  Default is [].
520
521                * {disc_only_copies,  Nodelist},  where  Nodelist is a list of
522                  the  nodes  where   this   table   is   supposed   to   have
523                  disc_only_copies.  A disc only table replica is kept on disc
524                  only and unlike the other replica types, the contents of the
525                  replica  do  not reside in RAM. These replicas are consider‐
526                  ably slower than replicas held in RAM.
527
528                * {index, Intlist}, where Intlist is a list of attribute names
529                  (atoms)  or  record  fields for which Mnesia is to build and
530                  maintain an extra index table. The qlc query compiler may be
531                  able to optimize queries if there are indexes available.
532
533                * {load_order, Integer}. The load order priority is by default
534                  0 (zero) but can be set to any integer. The tables with  the
535                  highest load order priority are loaded first at startup.
536
537                * {majority, Flag}, where Flag must be a boolean. If true, any
538                  (non-dirty) update to the table is aborted, unless a  major‐
539                  ity of the table replicas are available for the commit. When
540                  used on a fragmented table, all fragments are given the same
541                  the same majority setting.
542
543                * {ram_copies,  Nodelist},  where  Nodelist  is  a list of the
544                  nodes where this table is supposed to have RAM copies. A ta‐
545                  ble  replica  of type ram_copies is not written to disc on a
546                  per transaction basis. ram_copies replicas can be dumped  to
547                  disc  with  the  function  mnesia:dump_tables(Tabs). Default
548                  value for this attribute is [node()].
549
550                * {record_name, Name}, where Name must be an atom. All records
551                  stored  in  the  table must have this name as the first ele‐
552                  ment. It defaults to the same name as the table name.
553
554                * {snmp, SnmpStruct}. For a  description  of  SnmpStruct,  see
555                  mnesia:snmp_open_table/2.  If  this  attribute is present in
556                  ArgList to mnesia:create_table/2, the table  is  immediately
557                  accessible  by SNMP. Therefore applications that use SNMP to
558                  manipulate and control the system can  be  designed  easily,
559                  since  Mnesia  provides a direct mapping between the logical
560                  tables that make up an  SNMP  control  application  and  the
561                  physical data that makes up a Mnesia table.
562
563                * {storage_properties,  [{Backend,  Properties}] forwards more
564                  properties to the back end storage. Backend can currently be
565                  ets  or  dets.  Properties  is a list of options sent to the
566                  back end storage during table  creation.  Properties  cannot
567                  contain  properties  already used by Mnesia, such as type or
568                  named_table.
569
570                  For example:
571
572                mnesia:create_table(table, [{ram_copies, [node()]}, {disc_only_copies, nodes()},
573                       {storage_properties,
574                        [{ets, [compressed]}, {dets, [{auto_save, 5000}]} ]}])
575
576                * {type, Type}, where Type must be either of  the  atoms  set,
577                  ordered_set,  or  bag. Default is set. In a set, all records
578                  have unique keys. In a bag, several  records  can  have  the
579                  same  key, but the record content is unique. If a non-unique
580                  record is stored, the old conflicting records are  overwrit‐
581                  ten.
582
583                  Notice  that  currently  ordered_set  is  not  supported for
584                  disc_only_copies.
585
586                * {local_content, Bool}, where Bool is true or false.  Default
587                  is false.
588
589              For  example,  the  following  call  creates  the  person  table
590              (defined earlier) and replicates it on two nodes:
591
592              mnesia:create_table(person,
593                  [{ram_copies, [N1, N2]},
594                   {attributes, record_info(fields, person)}]).
595
596              If it is required that Mnesia must build and maintain  an  extra
597              index  table on attribute address of all the person records that
598              are inserted in the table, the following code would be issued:
599
600              mnesia:create_table(person,
601                  [{ram_copies, [N1, N2]},
602                   {index, [address]},
603                   {attributes, record_info(fields, person)}]).
604
605
606              The specification of index and attributes can be  hard-coded  as
607              {index, [2]} and {attributes, [name, age, address, salary, chil‐
608              dren]}, respectively.
609
610              mnesia:create_table/2 writes records into the table schema. This
611              function,  and  all  other  schema  manipulation  functions, are
612              implemented with the normal transaction management system.  This
613              guarantees  that schema updates are performed on all nodes in an
614              atomic manner.
615
616       deactivate_checkpoint(Name) -> ok | {error, Reason}
617
618              The checkpoint is automatically deactivated  when  some  of  the
619              tables  involved  have  no  retainer  attached to them. This can
620              occur when nodes go down or when a replica  is  deleted.  Check‐
621              points are also deactivated with this function. Name is the name
622              of an active checkpoint.
623
624       del_table_copy(Tab, Node) -> {aborted, R} | {atomic, ok}
625
626              Deletes the replica of table Tab at node  Node.  When  the  last
627              replica  is  deleted  with  this  function, the table disappears
628              entirely.
629
630              This function can also be used to delete a replica of the  table
631              named  schema. The Mnesia node is then removed. Notice that Mne‐
632              sia must be stopped on the node first.
633
634       del_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}
635
636              Deletes the index on attribute with name AttrName in a table.
637
638       delete({Tab, Key}) -> transaction abort | ok
639
640              Calls mnesia:delete(Tab, Key, write).
641
642       delete(Tab, Key, LockKind) -> transaction abort | ok
643
644              Deletes all records in table Tab with the key Key.
645
646              The  semantics  of  this  function  is  context-sensitive.   For
647              details,   see  mnesia:activity/4.  In  transaction-context,  it
648              acquires a lock of type LockKind in the record.  Currently,  the
649              lock types write and sticky_write are supported.
650
651       delete_object(Record) -> transaction abort | ok
652
653              Calls  mnesia:delete_object(Tab,  Record,  write),  where Tab is
654              element(1, Record).
655
656       delete_object(Tab, Record, LockKind) -> transaction abort | ok
657
658              If a table is of type bag, it can sometimes be needed to  delete
659              only  some  of  the records with a certain key. This can be done
660              with the function delete_object/3. A  complete  record  must  be
661              supplied to this function.
662
663              The   semantics  of  this  function  is  context-sensitive.  For
664              details,  see  mnesia:activity/4.  In  transaction-context,   it
665              acquires  a  lock of type LockKind on the record. Currently, the
666              lock types write and sticky_write are supported.
667
668       delete_schema(DiscNodes) -> ok | {error,Reason}
669
670              Deletes a database  created  with  mnesia:create_schema/1.  mne‐
671              sia:delete_schema/1  fails  if  any of the Erlang nodes given as
672              DiscNodes are not alive, or if Mnesia is running on any  of  the
673              nodes.
674
675              After the database is deleted, it can still be possible to start
676              Mnesia as a disc-less node. This depends  on  how  configuration
677              parameter schema_location is set.
678
679          Warning:
680              Use  this  function  with  extreme caution, as it makes existing
681              persistent data obsolete. Think twice before using it.
682
683
684       delete_table(Tab) -> {aborted, Reason} | {atomic, ok}
685
686              Permanently deletes all replicas of table Tab.
687
688       dirty_all_keys(Tab) -> KeyList | exit({aborted, Reason})
689
690              Dirty equivalent of the function mnesia:all_keys/1.
691
692       dirty_delete({Tab, Key}) -> ok | exit({aborted, Reason})
693
694              Calls mnesia:dirty_delete(Tab, Key).
695
696       dirty_delete(Tab, Key) -> ok | exit({aborted, Reason})
697
698              Dirty equivalent of the function mnesia:delete/3.
699
700       dirty_delete_object(Record)
701
702              Calls mnesia:dirty_delete_object(Tab, Record), where Tab is ele‐
703              ment(1, Record).
704
705       dirty_delete_object(Tab, Record)
706
707              Dirty equivalent of the function mnesia:delete_object/3.
708
709       dirty_first(Tab) -> Key | exit({aborted, Reason})
710
711              Records  in set or bag tables are not ordered. However, there is
712              an ordering of the records that is unknown to the  user.  There‐
713              fore,  a  table can be traversed by this function with the func‐
714              tion mnesia:dirty_next/2.
715
716              If there are no records in the table, this function returns  the
717              atom  '$end_of_table'.  It  is therefore highly undesirable, but
718              not disallowed, to use  this  atom  as  the  key  for  any  user
719              records.
720
721       dirty_index_match_object(Pattern, Pos)
722
723              Starts mnesia:dirty_index_match_object(Tab, Pattern, Pos), where
724              Tab is element(1, Pattern).
725
726       dirty_index_match_object(Tab, Pattern, Pos)
727
728              Dirty equivalent of the function mnesia:index_match_object/4.
729
730       dirty_index_read(Tab, SecondaryKey, Pos)
731
732              Dirty equivalent of the function mnesia:index_read/3.
733
734       dirty_last(Tab) -> Key | exit({aborted, Reason})
735
736              Works exactly like mnesia:dirty_first/1  but  returns  the  last
737              object  in Erlang term order for the ordered_set table type. For
738              all   other   table   types,   mnesia:dirty_first/1   and   mne‐
739              sia:dirty_last/1 are synonyms.
740
741       dirty_match_object(Pattern) -> RecordList | exit({aborted, Reason})
742
743              Calls mnesia:dirty_match_object(Tab, Pattern), where Tab is ele‐
744              ment(1, Pattern).
745
746       dirty_match_object(Tab, Pattern) -> RecordList  |  exit({aborted,  Rea‐
747       son})
748
749              Dirty equivalent of the function mnesia:match_object/3.
750
751       dirty_next(Tab, Key) -> Key | exit({aborted, Reason})
752
753              Traverses  a table and performs operations on all records in the
754              table. When the end of the table is  reached,  the  special  key
755              '$end_of_table'  is  returned. Otherwise, the function returns a
756              key that can be used to read the actual record. The behavior  is
757              undefined if another Erlang process performs write operations on
758              the table while it is being traversed  with  the  function  mne‐
759              sia:dirty_next/2.
760
761       dirty_prev(Tab, Key) -> Key | exit({aborted, Reason})
762
763              Works  exactly like mnesia:dirty_next/2 but returns the previous
764              object in Erlang term order for the ordered_set table type.  For
765              all    other   table   types,   mnesia:dirty_next/2   and   mne‐
766              sia:dirty_prev/2 are synonyms.
767
768       dirty_read({Tab, Key}) -> ValueList | exit({aborted, Reason}
769
770              Calls mnesia:dirty_read(Tab, Key).
771
772       dirty_read(Tab, Key) -> ValueList | exit({aborted, Reason}
773
774              Dirty equivalent of the function mnesia:read/3.
775
776       dirty_select(Tab, MatchSpec) -> ValueList | exit({aborted, Reason}
777
778              Dirty equivalent of the function mnesia:select/2.
779
780       dirty_slot(Tab, Slot) -> RecordList | exit({aborted, Reason})
781
782              Traverses a table in a  manner  similar  to  the  function  mne‐
783              sia:dirty_next/2.  A table has a number of slots that range from
784              0  (zero)  to  an  unknown  upper  bound.  The   function   mne‐
785              sia:dirty_slot/2  returns  the special atom '$end_of_table' when
786              the end of the table is reached. The behavior of  this  function
787              is  undefined  if  a  write  operation is performed on the table
788              while it is being traversed.
789
790       dirty_update_counter({Tab, Key}, Incr) -> NewVal | exit({aborted,  Rea‐
791       son})
792
793              Calls mnesia:dirty_update_counter(Tab, Key, Incr).
794
795       dirty_update_counter(Tab,  Key,  Incr)  -> NewVal | exit({aborted, Rea‐
796       son})
797
798              Mnesia has no special counter records. However, records  of  the
799              form {Tab, Key, Integer} can be used as (possibly disc-resident)
800              counters when Tab is a set. This function updates a counter with
801              a  positive  or  negative  number.  However,  counters can never
802              become less than zero. There  are  two  significant  differences
803              between  this  function  and  the  action  of  first reading the
804              record, performing the arithmetics, and then writing the record:
805
806                * It is much more efficient.
807
808                * mnesia:dirty_update_counter/3  is  performed  as  an  atomic
809                  operation although it is not protected by a transaction.
810
811              If  two processes perform mnesia:dirty_update_counter/3 simulta‐
812              neously, both updates take effect without the risk of losing one
813              of the updates. The new value NewVal of the counter is returned.
814
815              If Key do not exists, a new record is created with value Incr if
816              it is larger than 0, otherwise it is set to 0.
817
818       dirty_write(Record) -> ok | exit({aborted, Reason})
819
820              Calls mnesia:dirty_write(Tab, Record), where Tab  is  element(1,
821              Record).
822
823       dirty_write(Tab, Record) -> ok | exit({aborted, Reason})
824
825              Dirty equivalent of the function mnesia:write/3.
826
827       dump_log() -> dumped
828
829              Performs  a  user-initiated  dump of the local log file. This is
830              usually not necessary, as Mnesia by default manages  this  auto‐
831              matically.  See configuration parameters dump_log_time_threshold
832              and dump_log_write_threshold.
833
834       dump_tables(TabList) -> {atomic, ok} | {aborted, Reason}
835
836              Dumps a set of ram_copies tables to disc. The next time the sys‐
837              tem  is  started, these tables are initiated with the data found
838              in the files that are the result  of  this  dump.  None  of  the
839              tables can have disc-resident replicas.
840
841       dump_to_textfile(Filename)
842
843              Dumps  all  local  tables  of  a Mnesia system into a text file,
844              which can be edited (by  a  normal  text  editor)  and  then  be
845              reloaded with mnesia:load_textfile/1. Only use this function for
846              educational purposes. Use other  functions  to  deal  with  real
847              backups.
848
849       error_description(Error) -> String
850
851              All  Mnesia  transactions, including all the schema update func‐
852              tions, either return value {atomic, Val} or the tuple  {aborted,
853              Reason}.  Reason  can  be  either  of the atoms in the following
854              list. The function  error_description/1  returns  a  descriptive
855              string that describes the error.
856
857                * nested_transaction.  Nested  transactions are not allowed in
858                  this context.
859
860                * badarg. Bad or invalid argument, possibly bad type.
861
862                * no_transaction. Operation not allowed outside transactions.
863
864                * combine_error. Table options illegally combined.
865
866                * bad_index. Index already exists, or was out of bounds.
867
868                * already_exists. Schema option to be activated is already on.
869
870                * index_exists. Some operations cannot be performed on  tables
871                  with an index.
872
873                * no_exists.  Tried to perform operation on non-existing (not-
874                  alive) item.
875
876                * system_limit. A system limit was exhausted.
877
878                * mnesia_down. A transaction  involves  records  on  a  remote
879                  node,  which  became  unavailable before the transaction was
880                  completed. Records are no longer available elsewhere in  the
881                  network.
882
883                * not_a_db_node.  A  node was mentioned that does not exist in
884                  the schema.
885
886                * bad_type. Bad type specified in argument.
887
888                * node_not_running. Node is not running.
889
890                * truncated_binary_file. Truncated binary in file.
891
892                * active. Some  delete  operations  require  that  all  active
893                  records are removed.
894
895                * illegal. Operation not supported on this record.
896
897              Error can be Reason, {error, Reason}, or {aborted, Reason}. Rea‐
898              son can be an atom or a tuple with Reason  as  an  atom  in  the
899              first field.
900
901              The  following  examples  illustrate  a function that returns an
902              error, and the method to retrieve more detailed  error  informa‐
903              tion:
904
905                * The  function mnesia:create_table(bar, [{attributes, 3.14}])
906                  returns the tuple  {aborted,Reason},  where  Reason  is  the
907                  tuple {bad_type,bar,3.14000}.
908
909                * The  function  mnesia:error_description(Reason)  returns the
910                  term {"Bad type on  some  provided  arguments",bar,3.14000},
911                  which is an error description suitable for display.
912
913       ets(Fun, [, Args]) -> ResultOfFun | exit(Reason)
914
915              Calls the Fun in a raw context that is not protected by a trans‐
916              action. The Mnesia function call is performed  in  the  Fun  and
917              performed  directly  on  the  local ETS tables on the assumption
918              that the local storage type is ram_copies and the tables are not
919              replicated  to  other nodes. Subscriptions are not triggered and
920              checkpoints are not updated, but  it  is  extremely  fast.  This
921              function can also be applied to disc_copies tables if all opera‐
922              tions are read only. For details, see mnesia:activity/4 and  the
923              User's Guide.
924
925              Notice that calling (nesting) a mnesia:ets inside a transaction-
926              context inherits the transaction semantics.
927
928       first(Tab) -> Key | transaction abort
929
930              Records in set or bag tables are not ordered. However, there  is
931              an  ordering of the records that is unknown to the user. A table
932              can therefore be traversed by this function  with  the  function
933              mnesia:next/2.
934
935              If  there are no records in the table, this function returns the
936              atom '$end_of_table'. It is therefore  highly  undesirable,  but
937              not  disallowed,  to  use  this  atom  as  the  key for any user
938              records.
939
940       foldl(Function, Acc, Table) -> NewAcc | transaction abort
941
942              Iterates over the table Table and calls Function(Record, NewAcc)
943              for each Record in the table. The term returned from Function is
944              used as the second argument in the next call to Function.
945
946              foldl returns the  same  term  as  the  last  call  to  Function
947              returned.
948
949       foldr(Function, Acc, Table) -> NewAcc | transaction abort
950
951              Works  exactly  like foldl/3 but iterates the table in the oppo‐
952              site order for the ordered_set table type. For all  other  table
953              types, foldr/3 and foldl/3 are synonyms.
954
955       force_load_table(Tab) -> yes | ErrorDescription
956
957              The  Mnesia  algorithm  for  table  load can lead to a situation
958              where a table cannot be loaded. This  situation  occurs  when  a
959              node  is started and Mnesia concludes, or suspects, that another
960              copy of the table was active after this local copy became  inac‐
961              tive because of a system crash.
962
963              If  this  situation is not acceptable, this function can be used
964              to override the strategy of the  Mnesia  table  load  algorithm.
965              This  can lead to a situation where some transaction effects are
966              lost with an inconsistent  database  as  result,  but  for  some
967              applications high availability is more important than consistent
968              data.
969
970       index_match_object(Pattern, Pos) -> transaction abort | ObjList
971
972              Starts mnesia:index_match_object(Tab, Pattern, Pos, read), where
973              Tab is element(1, Pattern).
974
975       index_match_object(Tab,  Pattern, Pos, LockKind) -> transaction abort |
976       ObjList
977
978              In a manner similar to  the  function  mnesia:index_read/3,  any
979              index information can be used when trying to match records. This
980              function takes a pattern that obeys the same rules as the  func‐
981              tion  mnesia:match_object/3,  except that this function requires
982              the following conditions:
983
984                * The table Tab must have an index on position Pos.
985
986                * The element in position Pos in Pattern must be bound. Pos is
987                  an integer (#record.Field) or an attribute name.
988
989              The  two index search functions described here are automatically
990              started when searching tables with qlc list  comprehensions  and
991              also  when using the low-level mnesia:[dirty_]match_object func‐
992              tions.
993
994              The  semantics  of  this  function  is  context-sensitive.   For
995              details,   see  mnesia:activity/4.  In  transaction-context,  it
996              acquires a lock of type LockKind on the entire  table  or  on  a
997              single record. Currently, the lock type read is supported.
998
999       index_read(Tab, SecondaryKey, Pos) -> transaction abort | RecordList
1000
1001              Assume  that  there  is  an  index on position Pos for a certain
1002              record type. This function can be used to read the records with‐
1003              out  knowing the actual key for the record. For example, with an
1004              index  in  position  1  of   table   person,   the   call   mne‐
1005              sia:index_read(person,  36,  #person.age)  returns a list of all
1006              persons with age 36. Pos can also be an attribute  name  (atom),
1007              but  if the notation mnesia:index_read(person, 36, age) is used,
1008              the field position is searched for in runtime, for each call.
1009
1010              The  semantics  of  this  function  is  context-sensitive.   For
1011              details,   see  mnesia:activity/4.  In  transaction-context,  it
1012              acquires a read lock on the entire table.
1013
1014       info() -> ok
1015
1016              Prints system information on the terminal. This function can  be
1017              used even if Mnesia is not started. However, more information is
1018              displayed if Mnesia is started.
1019
1020       install_fallback(Opaque) -> ok | {error,Reason}
1021
1022              Calls  mnesia:install_fallback(Opaque,  Args),  where  Args   is
1023              [{scope, global}].
1024
1025       install_fallback(Opaque), BackupMod) -> ok | {error,Reason}
1026
1027              Calls   mnesia:install_fallback(Opaque,  Args),  where  Args  is
1028              [{scope, global}, {module, BackupMod}].
1029
1030       install_fallback(Opaque, Args) -> ok | {error,Reason}
1031
1032              Installs a backup as fallback. The fallback is used  to  restore
1033              the  database  at  the  next  startup. Installation of fallbacks
1034              requires Erlang to be operational on all the involved nodes, but
1035              it does not matter if Mnesia is running or not. The installation
1036              of the fallback fails if the local node is not one of the  disc-
1037              resident nodes in the backup.
1038
1039              Args is a list of the following tuples:
1040
1041                * {module,  BackupMod}.  All  accesses of the backup media are
1042                  performed through a callback module named  BackupMod.  Argu‐
1043                  ment  Opaque  is forwarded to the callback module, which can
1044                  interpret it as it wishes. The default  callback  module  is
1045                  called  mnesia_backup and it interprets argument Opaque as a
1046                  local filename. The default for this module is also  config‐
1047                  urable   through   configuration   parameter   -mnesia  mne‐
1048                  sia_backup.
1049
1050                * {scope, Scope}. The Scope of a fallback is either global for
1051                  the  entire  database or local for one node. By default, the
1052                  installation of a fallback  is  a  global  operation,  which
1053                  either is performed on all nodes with a disc-resident schema
1054                  or none. Which nodes that are  disc-resident  is  determined
1055                  from the schema information in the backup.
1056
1057                  If  Scope  of  the  operation is local, the fallback is only
1058                  installed on the local node.
1059
1060                * {mnesia_dir, AlternateDir}. This argument is only  valid  if
1061                  the scope of the installation is local. Normally the instal‐
1062                  lation of a fallback is targeted to the Mnesia directory, as
1063                  configured  with configuration parameter -mnesia dir. But by
1064                  explicitly  supplying  an  AlternateDir,  the  fallback   is
1065                  installed  there regardless of the Mnesia directory configu‐
1066                  ration parameter setting. After installation of  a  fallback
1067                  on  an alternative Mnesia directory, that directory is fully
1068                  prepared for use as an active Mnesia directory.
1069
1070                  This is a dangerous feature that must be used with care.  By
1071                  unintentional  mixing  of directories, you can easily end up
1072                  with  an  inconsistent  database,  if  the  same  backup  is
1073                  installed on more than one directory.
1074
1075       is_transaction() -> boolean
1076
1077              When  this function is executed inside a transaction-context, it
1078              returns true, otherwise false.
1079
1080       last(Tab) -> Key | transaction abort
1081
1082              Works exactly like mnesia:first/1, but returns the  last  object
1083              in  Erlang  term  order  for the ordered_set table type. For all
1084              other table types, mnesia:first/1  and  mnesia:last/1  are  syn‐
1085              onyms.
1086
1087       load_textfile(Filename)
1088
1089              Loads  a  series  of definitions and data found in the text file
1090              (generated with  mnesia:dump_to_textfile/1)  into  Mnesia.  This
1091              function  also  starts Mnesia and possibly creates a new schema.
1092              This function is intended for educational purposes only.  It  is
1093              recommended to use other functions to deal with real backups.
1094
1095       lock(LockItem, LockKind) -> Nodes | ok | transaction abort
1096
1097              Write  locks  are normally acquired on all nodes where a replica
1098              of the table resides (and is active). Read locks are acquired on
1099              one node (the local node if a local replica exists). Most of the
1100              context-sensitive access functions acquire an implicit  lock  if
1101              they  are started in a transaction-context. The granularity of a
1102              lock can either be a single record or an entire table.
1103
1104              The normal use is to call  the  function  without  checking  the
1105              return  value,  as  it  exits if it fails and the transaction is
1106              restarted by the transaction manager. It returns all the  locked
1107              nodes if a write lock is acquired and ok if it was a read lock.
1108
1109              The function mnesia:lock/2 is intended to support explicit lock‐
1110              ing on tables, but is also intended for  situations  when  locks
1111              need  to  be  acquired  regardless of how tables are replicated.
1112              Currently, two kinds of LockKind are supported:
1113
1114                write:
1115                  Write locks are exclusive. This means that if  one  transac‐
1116                  tion  manages  to  acquire a write lock on an item, no other
1117                  transaction can acquire any kind of lock on the same item.
1118
1119                read:
1120                  Read locks can be shared. This means that if one transaction
1121                  manages  to  acquire  a read lock on an item, other transac‐
1122                  tions can also acquire a read lock on the  same  item.  How‐
1123                  ever, if someone has a read lock, no one can acquire a write
1124                  lock at the same item. If someone has a write lock,  no  one
1125                  can  acquire  either a read lock or a write lock at the same
1126                  item.
1127
1128              Conflicting lock requests are automatically queued if  there  is
1129              no  risk of a deadlock. Otherwise the transaction must be termi‐
1130              nated and executed again. Mnesia does this automatically as long
1131              as  the  upper  limit of the maximum retries is not reached. For
1132              details, see mnesia:transaction/3.
1133
1134              For the sake  of  completeness,  sticky  write  locks  are  also
1135              described  here  even if a sticky write lock is not supported by
1136              this function:
1137
1138                sticky_write:
1139                  Sticky write locks are a mechanism that can be used to opti‐
1140                  mize write lock acquisition. If your application uses repli‐
1141                  cated tables mainly for fault tolerance (as opposed to  read
1142                  access  optimization  purpose), sticky locks can be the best
1143                  option available.
1144
1145                  When a sticky write lock is acquired, all nodes are informed
1146                  which  node  is  locked. Then, sticky lock requests from the
1147                  same node are performed as a  local  operation  without  any
1148                  communication  with  other nodes. The sticky lock lingers on
1149                  the node even after the transaction ends. For  details,  see
1150                  the User's Guide.
1151
1152              Currently, this function supports two kinds of LockItem:
1153
1154                {table, Tab}:
1155                  This  acquires  a  lock of type LockKind on the entire table
1156                  Tab.
1157
1158                {global, GlobalKey, Nodes}:
1159                  This acquires a lock of type LockKind on the global resource
1160                  GlobalKey.  The  lock is acquired on all active nodes in the
1161                  Nodes list.
1162
1163              Locks are released when the outermost transaction ends.
1164
1165              The  semantics  of  this  function  is  context-sensitive.   For
1166              details,   see  mnesia:activity/4.  In  transaction-context,  it
1167              acquires locks, otherwise it ignores the request.
1168
1169       match_object(Pattern) -> transaction abort | RecList
1170
1171              Calls mnesia:match_object(Tab, Pattern, read), where Tab is ele‐
1172              ment(1, Pattern).
1173
1174       match_object(Tab, Pattern, LockKind) -> transaction abort | RecList
1175
1176              Takes  a  pattern  with  "don't care" variables denoted as a '_'
1177              parameter. This function returns a list of records that  matched
1178              the  pattern. Since the second element of a record in a table is
1179              considered to be the key for the record, the performance of this
1180              function depends on whether this key is bound or not.
1181
1182              For  example, the call mnesia:match_object(person, {person, '_',
1183              36, '_', '_'}, read) returns a list of all person  records  with
1184              an age field of 36.
1185
1186              The function mnesia:match_object/3 automatically uses indexes if
1187              these exist. However, no heuristics are performed to select  the
1188              best index.
1189
1190              The   semantics  of  this  function  is  context-sensitive.  For
1191              details,  see  mnesia:activity/4.  In  transaction-context,   it
1192              acquires a lock of type LockKind on the entire table or a single
1193              record. Currently, the lock type read is supported.
1194
1195       move_table_copy(Tab, From, To) -> {aborted, Reason} | {atomic, ok}
1196
1197              Moves the copy of table Tab from node From to node To.
1198
1199              The storage type is preserved. For example, a  RAM  table  moved
1200              from  one node remains a RAM on the new node. Other transactions
1201              can still read and write in the table while it is being moved.
1202
1203              This function cannot be used on local_content tables.
1204
1205       next(Tab, Key) -> Key | transaction abort
1206
1207              Traverses a table and performs operations on all records in  the
1208              table.  When  the  end  of the table is reached, the special key
1209              '$end_of_table' is returned. Otherwise the  function  returns  a
1210              key that can be used to read the actual record.
1211
1212       prev(Tab, Key) -> Key | transaction abort
1213
1214              Works  exactly  like  mnesia:next/2,  but  returns  the previous
1215              object in Erlang term order for the ordered_set table type.  For
1216              all  other table types, mnesia:next/2 and mnesia:prev/2 are syn‐
1217              onyms.
1218
1219       read({Tab, Key}) -> transaction abort | RecordList
1220
1221              Calls function mnesia:read(Tab, Key, read).
1222
1223       read(Tab, Key) -> transaction abort | RecordList
1224
1225              Calls function mnesia:read(Tab, Key, read).
1226
1227       read(Tab, Key, LockKind) -> transaction abort | RecordList
1228
1229              Reads all records from table Tab with key Key. This function has
1230              the same semantics regardless of the location of Tab. If the ta‐
1231              ble is of type  bag,  the  function  mnesia:read(Tab,  Key)  can
1232              return  an  arbitrarily  long list. If the table is of type set,
1233              the list is either of length 1, or [].
1234
1235              The  semantics  of  this  function  is  context-sensitive.   For
1236              details,   see  mnesia:activity/4.  In  transaction-context,  it
1237              acquires a lock of type  LockKind.  Currently,  the  lock  types
1238              read, write, and sticky_write are supported.
1239
1240              If  the user wants to update the record, it is more efficient to
1241              use write/sticky_write as the LockKind. If majority checking  is
1242              active  on  the  table, it is checked as soon as a write lock is
1243              attempted. This can be used to end quickly if the majority  con‐
1244              dition is not met.
1245
1246       read_lock_table(Tab) -> ok | transaction abort
1247
1248              Calls the function mnesia:lock({table, Tab}, read).
1249
1250       report_event(Event) -> ok
1251
1252              When  tracing a system of Mnesia applications it is useful to be
1253              able to interleave Mnesia own  events  with  application-related
1254              events that give information about the application context.
1255
1256              Whenever the application begins a new and demanding Mnesia task,
1257              or if it enters a new interesting phase in its execution, it can
1258              be  a  good  idea to use mnesia:report_event/1. Event can be any
1259              term and generates a {mnesia_user, Event}  event  for  any  pro‐
1260              cesses that subscribe to Mnesia system events.
1261
1262       restore(Opaque, Args) -> {atomic, RestoredTabs} |{aborted, Reason}
1263
1264              With  this function, tables can be restored online from a backup
1265              without restarting Mnesia. Opaque is  forwarded  to  the  backup
1266              module. Args is a list of the following tuples:
1267
1268                * {module,BackupMod}.  The  backup module BackupMod is used to
1269                  access the backup media. If omitted, the default backup mod‐
1270                  ule is used.
1271
1272                * {skip_tables,  TabList},  where  TabList is a list of tables
1273                  that is not to be read from the backup.
1274
1275                * {clear_tables, TabList}, where TabList is a list  of  tables
1276                  that is to be cleared before the records from the backup are
1277                  inserted. That is, all records in  the  tables  are  deleted
1278                  before the tables are restored. Schema information about the
1279                  tables is not cleared or read from the backup.
1280
1281                * {keep_tables, TabList}, where TabList is a  list  of  tables
1282                  that is not to be cleared before the records from the backup
1283                  are inserted. That is, the records in the backup  are  added
1284                  to  the  records  in the table. Schema information about the
1285                  tables is not cleared or read from the backup.
1286
1287                * {recreate_tables, TabList},  where  TabList  is  a  list  of
1288                  tables  that  is to be recreated before the records from the
1289                  backup are inserted. The tables are first deleted  and  then
1290                  created with the schema information from the backup. All the
1291                  nodes in the backup need to be operational.
1292
1293                * {default_op, Operation}, where Operation is  either  of  the
1294                  operations skip_tables, clear_tables, keep_tables, or recre‐
1295                  ate_tables. The default operation specifies which  operation
1296                  that  is  to  be  used on tables from the backup that is not
1297                  specified in any of the mentioned lists. If omitted,  opera‐
1298                  tion clear_tables is used.
1299
1300              The  affected  tables  are  write-locked during the restoration.
1301              However, regardless of the lock conflicts caused  by  this,  the
1302              applications can continue to do their work while the restoration
1303              is being performed. The restoration is performed as  one  single
1304              transaction.
1305
1306              If the database is huge, it it not always possible to restore it
1307              online. In such cases, restore the old database by installing  a
1308              fallback and then restart.
1309
1310       s_delete({Tab, Key}) -> ok | transaction abort
1311
1312              Calls the function mnesia:delete(Tab, Key, sticky_write)
1313
1314       s_delete_object(Record) -> ok | transaction abort
1315
1316              Calls    the    function    mnesia:delete_object(Tab,    Record,
1317              sticky_write), where Tab is element(1, Record).
1318
1319       s_write(Record) -> ok | transaction abort
1320
1321              Calls  the  function  mnesia:write(Tab,  Record,  sticky_write),
1322              where Tab is element(1, Record).
1323
1324       schema() -> ok
1325
1326              Prints information about all table definitions on the terminal.
1327
1328       schema(Tab) -> ok
1329
1330              Prints information about one table definition on the terminal.
1331
1332       select(Tab, MatchSpec [, Lock]) -> transaction abort | [Object]
1333
1334              Matches the objects in table Tab using a match_spec as described
1335              in the ets:select/3. Optionally a lock  read  or  write  can  be
1336              given  as  the third argument. Default is read. The return value
1337              depends on MatchSpec.
1338
1339              Notice that for best performance, select is to  be  used  before
1340              any  modifying  operations  are  done  on that table in the same
1341              transaction. That is, do  not  use  write  or  delete  before  a
1342              select.
1343
1344              In its simplest forms, the match_spec look as follows:
1345
1346                * MatchSpec = [MatchFunction]
1347
1348                * MatchFunction = {MatchHead, [Guard], [Result]}
1349
1350                * MatchHead = tuple() | record()
1351
1352                * Guard = {"Guardtest name", ...}
1353
1354                * Result = "Term construct"
1355
1356              For  a complete description of select, see the ERTS User's Guide
1357              and the ets manual page in STDLIB.
1358
1359              For example, to find the names of all male persons older than 30
1360              in table Tab:
1361
1362              MatchHead = #person{name='$1', sex=male, age='$2', _='_'},
1363              Guard = {'>', '$2', 30},
1364              Result = '$1',
1365              mnesia:select(Tab,[{MatchHead, [Guard], [Result]}]),
1366
1367       select(Tab,   MatchSpec,   NObjects,   Lock)  ->  transaction  abort  |
1368       {[Object],Cont} | '$end_of_table'
1369
1370              Matches the objects in table Tab using a match_spec as described
1371              in  the  ERTS  User's  Guide, and returns a chunk of terms and a
1372              continuation. The wanted number of returned terms  is  specified
1373              by  argument  NObjects.  The lock argument can be read or write.
1374              The continuation is to be used as argument  to  mnesia:select/1,
1375              if more or all answers are needed.
1376
1377              Notice  that  for  best performance, select is to be used before
1378              any modifying operations are done on  that  table  in  the  same
1379              transaction.  That  is, do not use mnesia:write or mnesia:delete
1380              before a mnesia:select. For efficiency, NObjects is a  recommen‐
1381              dation  only  and  the result can contain anything from an empty
1382              list to all available results.
1383
1384       select(Cont) -> transaction abort | {[Object],Cont} | '$end_of_table'
1385
1386              Selects more objects with the match specification  initiated  by
1387              mnesia:select/4.
1388
1389              Notice  that  any modifying operations, that is, mnesia:write or
1390              mnesia:delete, that are done  between  the  mnesia:select/4  and
1391              mnesia:select/1 calls are not visible in the result.
1392
1393       set_debug_level(Level) -> OldLevel
1394
1395              Changes  the  internal  debug  level of Mnesia. For details, see
1396              Section Configuration Parameters.
1397
1398       set_master_nodes(MasterNodes) -> ok | {error, Reason}
1399
1400              For each table Mnesia determines its  replica  nodes  (TabNodes)
1401              and  starts  mnesia:set_master_nodes(Tab, TabMasterNodes). where
1402              TabMasterNodes is the intersection of MasterNodes and  TabNodes.
1403              For semantics, see mnesia:set_master_nodes/2.
1404
1405       set_master_nodes(Tab, MasterNodes) -> ok | {error, Reason}
1406
1407              If  the application detects a communication failure (in a poten‐
1408              tially partitioned network) that can have caused an inconsistent
1409              database,  it  can use the function mnesia:set_master_nodes(Tab,
1410              MasterNodes) to define from which nodes  each  table  is  to  be
1411              loaded.  At  startup,  the Mnesia normal table load algorithm is
1412              bypassed and the table is loaded from one of  the  master  nodes
1413              defined  for  the table, regardless of when and if Mnesia termi‐
1414              nated on other nodes. MasterNodes can only contain  nodes  where
1415              the  table  has a replica. If the MasterNodes list is empty, the
1416              master node recovery  mechanism  for  the  particular  table  is
1417              reset,  and  the  normal  load  mechanism  is  used  at the next
1418              restart.
1419
1420              The master node setting is  always  local.  It  can  be  changed
1421              regardless if Mnesia is started or not.
1422
1423              The  database  can  also  become  inconsistent  if configuration
1424              parameter   max_wait_for_decision   is   used   or    if    mne‐
1425              sia:force_load_table/1 is used.
1426
1427       snmp_close_table(Tab) -> {aborted, R} | {atomic, ok}
1428
1429              Removes the possibility for SNMP to manipulate the table.
1430
1431       snmp_get_mnesia_key(Tab, RowIndex) -> {ok, Key} | undefined
1432
1433              Types:
1434
1435                 Tab ::= atom()
1436                 RowIndex ::= [integer()]
1437                 Key ::= key() | {key(), key(), ...}
1438                 key() ::= integer() | string() | [integer()]
1439
1440              Transforms an SNMP index to the corresponding Mnesia key. If the
1441              SNMP table has multiple keys, the key is a tuple of the key col‐
1442              umns.
1443
1444       snmp_get_next_index(Tab, RowIndex) -> {ok, NextIndex} | endOfTable
1445
1446              Types:
1447
1448                 Tab ::= atom()
1449                 RowIndex ::= [integer()]
1450                 NextIndex ::= [integer()]
1451
1452              RowIndex can specify a non-existing row. Specifically, it can be
1453              the empty list. Returns the index of  the  next  lexicographical
1454              row.  If  RowIndex  is the empty list, this function returns the
1455              index of the first row in the table.
1456
1457       snmp_get_row(Tab, RowIndex) -> {ok, Row} | undefined
1458
1459              Types:
1460
1461                 Tab ::= atom()
1462                 RowIndex ::= [integer()]
1463                 Row ::= record(Tab)
1464
1465              Reads a row by its SNMP index. This index  is  specified  as  an
1466              SNMP Object Identifier, a list of integers.
1467
1468       snmp_open_table(Tab, SnmpStruct) -> {aborted, R} | {atomic, ok}
1469
1470              Types:
1471
1472                 Tab ::= atom()
1473                 SnmpStruct ::= [{key, type()}]
1474                 type() ::= type_spec() | {type_spec(), type_spec(), ...}
1475                 type_spec() ::= fix_string | string | integer
1476
1477              A  direct  one-to-one  mapping can be established between Mnesia
1478              tables and SNMP tables. Many telecommunication applications  are
1479              controlled  and  monitored by the SNMP protocol. This connection
1480              between Mnesia and  SNMP  makes  it  simple  and  convenient  to
1481              achieve this mapping.
1482
1483              Argument  SnmpStruct  is  a list of SNMP information. Currently,
1484              the only information needed is information about the  key  types
1485              in  the  table.  Multiple  keys cannot be handled in Mnesia, but
1486              many SNMP tables have multiple keys.  Therefore,  the  following
1487              convention  is  used:  if  a table has multiple keys, these must
1488              always be stored as a tuple of the keys. Information  about  the
1489              key types is specified as a tuple of atoms describing the types.
1490              The only significant type  is  fix_string.  This  means  that  a
1491              string has a fixed size.
1492
1493              For  example, the following causes table person to be ordered as
1494              an SNMP table:
1495
1496              mnesia:snmp_open_table(person, [{key, string}])
1497
1498              Consider the following schema for a table of company  employees.
1499              Each  employee  is identified by department number and name. The
1500              other table column stores the telephone number:
1501
1502              mnesia:create_table(employee,
1503                  [{snmp, [{key, {integer, string}}]},
1504                   {attributes, record_info(fields, employees)}]),
1505
1506              The corresponding SNMP table would have three  columns:  depart‐
1507              ment, name, and telno.
1508
1509              An  option is to have table columns that are not visible through
1510              the SNMP protocol. These columns must be the last columns of the
1511              table.  In  the previous example, the SNMP table could have col‐
1512              umns department and name only. The application  could  then  use
1513              column telno internally, but it would not be visible to the SNMP
1514              managers.
1515
1516              In a table monitored by SNMP, all  elements  must  be  integers,
1517              strings, or lists of integers.
1518
1519              When  a  table is SNMP ordered, modifications are more expensive
1520              than usual, O(logN). Also, more memory is used.
1521
1522              Notice that only the lexicographical  SNMP  ordering  is  imple‐
1523              mented in Mnesia, not the actual SNMP monitoring.
1524
1525       start() -> ok | {error, Reason}
1526
1527              Mnesia startup is asynchronous. The function call mnesia:start()
1528              returns the atom ok and then starts to initialize the  different
1529              tables.  Depending  on  the  size of the database, this can take
1530              some time, and the application  programmer  must  wait  for  the
1531              tables  that the application needs before they can be used. This
1532              is achieved by using the function mnesia:wait_for_tables/2.
1533
1534              The startup procedure for a set of Mnesia nodes is a fairly com‐
1535              plicated  operation. A Mnesia system consists of a set of nodes,
1536              with Mnesia started locally on  all  participating  nodes.  Nor‐
1537              mally,  each node has a directory where all the Mnesia files are
1538              written. This directory is referred to as the Mnesia  directory.
1539              Mnesia can also be started on disc-less nodes. For more informa‐
1540              tion about disc-less nodes, see mnesia:create_schema/1  and  the
1541              User's Guide.
1542
1543              The  set  of  nodes  that  makes up a Mnesia system is kept in a
1544              schema. Mnesia nodes can be added to or removed from the schema.
1545              The initial schema is normally created on disc with the function
1546              mnesia:create_schema/1.  On  disc-less  nodes,  a  tiny  default
1547              schema  is  generated  each  time  Mnesia is started. During the
1548              startup procedure, Mnesia exchanges schema  information  between
1549              the nodes to verify that the table definitions are compatible.
1550
1551              Each  schema  has  a  unique  cookie, which can be regarded as a
1552              unique schema identifier. The cookie must be  the  same  on  all
1553              nodes  where  Mnesia  is  supposed  to run. For details, see the
1554              User's Guide.
1555
1556              The schema file and all other files that Mnesia needs  are  kept
1557              in the Mnesia directory. The command-line option -mnesia dir Dir
1558              can be used to specify the location of  this  directory  to  the
1559              Mnesia system. If no such command-line option is found, the name
1560              of the directory defaults to Mnesia.Node.
1561
1562              application:start(mnesia) can also be used.
1563
1564       stop() -> stopped
1565
1566              Stops Mnesia locally on the current node.
1567
1568              application:stop(mnesia) can also be used.
1569
1570       subscribe(EventCategory) -> {ok, Node} | {error, Reason}
1571
1572              Ensures that a copy of all events of type EventCategory is  sent
1573              to  the  caller.  The available event types are described in the
1574              User's Guide.
1575
1576       sync_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason)
1577
1578              Calls the Fun in a context that is not protected by  a  transac‐
1579              tion.  The Mnesia function calls performed in the Fun are mapped
1580              to the corresponding dirty functions. It is performed in  almost
1581              the  same  context  as mnesia:async_dirty/1,2. The difference is
1582              that the operations  are  performed  synchronously.  The  caller
1583              waits  for  the  updates  to be performed on all active replicas
1584              before the Fun returns. For details, see  mnesia:activity/4  and
1585              the User's Guide.
1586
1587       sync_log() -> ok | {error, Reason}
1588
1589              Ensures  that  the local transaction log file is synced to disk.
1590              On a single node system, data written to disk tables  since  the
1591              last  dump  can  be  lost  if  there  is  a  power  outage.  See
1592              dump_log/0.
1593
1594       sync_transaction(Fun, [[,  Args],  Retries])  ->  {aborted,  Reason}  |
1595       {atomic, ResultOfFun}
1596
1597              Waits until data have been committed and logged to disk (if disk
1598              is used) on every involved node before it returns, otherwise  it
1599              behaves as mnesia:transaction/[1,2,3].
1600
1601              This  functionality  can be used to avoid that one process over‐
1602              loads a database on another node.
1603
1604       system_info(InfoKey) -> Info | exit({aborted, Reason})
1605
1606              Returns information about the Mnesia system, such as transaction
1607              statistics,  db_nodes,  and  configuration parameters. The valid
1608              keys are as follows:
1609
1610                * all. Returns a list of all local  system  information.  Each
1611                  element is a {InfoKey, InfoVal} tuple.
1612
1613                  New  InfoKeys can be added and old undocumented InfoKeys can
1614                  be removed without notice.
1615
1616                * access_module. Returns the name of module that is configured
1617                  to be the activity access callback module.
1618
1619                * auto_repair.  Returns true or false to indicate if Mnesia is
1620                  configured to start the auto-repair  facility  on  corrupted
1621                  disc files.
1622
1623                * backup_module.  Returns  the name of the module that is con‐
1624                  figured to be the backup callback module.
1625
1626                * checkpoints. Returns a list of the names of the  checkpoints
1627                  currently active on this node.
1628
1629                * event_module.  Returns  the  name  of the module that is the
1630                  event handler callback module.
1631
1632                * db_nodes. Returns the nodes  that  make  up  the  persistent
1633                  database.  Disc-less  nodes are only included in the list of
1634                  nodes if they explicitly have been added to the schema,  for
1635                  example,  with  mnesia:add_table_copy/3. The function can be
1636                  started even if Mnesia is not yet running.
1637
1638                * debug. Returns the current debug level of Mnesia.
1639
1640                * directory. Returns the name of the Mnesia directory. It  can
1641                  be called even if Mnesia is not yet running.
1642
1643                * dump_log_load_regulation.  Returns  a  boolean that tells if
1644                  Mnesia is configured to regulate the dumper process load.
1645
1646                  This feature is temporary and  will  be  removed  in  future
1647                  releases.
1648
1649                * dump_log_time_threshold.  Returns  the  time  threshold  for
1650                  transaction log dumps in milliseconds.
1651
1652                * dump_log_update_in_place. Returns a boolean  that  tells  if
1653                  Mnesia  is  configured  to  perform  the updates in the Dets
1654                  files directly, or if the updates are to be performed  in  a
1655                  copy of the Dets files.
1656
1657                * dump_log_write_threshold.  Returns  the  write threshold for
1658                  transaction log dumps as the number of writes to the  trans‐
1659                  action log.
1660
1661                * extra_db_nodes.  Returns a list of extra db_nodes to be con‐
1662                  tacted at startup.
1663
1664                * fallback_activated. Returns true if a fallback is activated,
1665                  otherwise false.
1666
1667                * held_locks.  Returns  a  list of all locks held by the local
1668                  Mnesia lock manager.
1669
1670                * is_running. Returns yes or no to indicate if Mnesia is  run‐
1671                  ning. It can also return starting or stopping. Can be called
1672                  even if Mnesia is not yet running.
1673
1674                * local_tables. Returns a list of all tables that are  config‐
1675                  ured to reside locally.
1676
1677                * lock_queue.  Returns  a  list  of  all transactions that are
1678                  queued for execution by the local lock manager.
1679
1680                * log_version. Returns the version number of the Mnesia trans‐
1681                  action log format.
1682
1683                * master_node_tables.  Returns  a  list  of all tables with at
1684                  least one master node.
1685
1686                * protocol_version. Returns the version number of  the  Mnesia
1687                  inter-process communication protocol.
1688
1689                * running_db_nodes.  Returns a list of nodes where Mnesia cur‐
1690                  rently is running. This function can be called even if  Mne‐
1691                  sia  is  not yet running, but it then has slightly different
1692                  semantics.
1693
1694                  If Mnesia is down on the local node,  the  function  returns
1695                  those  other db_nodes and extra_db_nodes that for the moment
1696                  are operational.
1697
1698                  If Mnesia is started, the function returns those nodes  that
1699                  Mnesia  on  the local node is fully connected to. Only those
1700                  nodes that Mnesia has exchanged schema information with  are
1701                  included  as  running_db_nodes.  After the merge of schemas,
1702                  the local Mnesia system is fully operable  and  applications
1703                  can  perform  access  of  remote replicas. Before the schema
1704                  merge, Mnesia only operates  locally.  Sometimes  there  are
1705                  more  nodes  included  in the running_db_nodes list than all
1706                  db_nodes and extra_db_nodes together.
1707
1708                * schema_location. Returns the initial schema location.
1709
1710                * subscribers. Returns a list  of  local  processes  currently
1711                  subscribing to system events.
1712
1713                * tables. Returns a list of all locally known tables.
1714
1715                * transactions.  Returns  a list of all currently active local
1716                  transactions.
1717
1718                * transaction_failures. Returns a number  that  indicates  how
1719                  many transactions have failed since Mnesia was started.
1720
1721                * transaction_commits.  Returns  a  number  that indicates how
1722                  many transactions have terminated successfully since  Mnesia
1723                  was started.
1724
1725                * transaction_restarts.  Returns  a  number that indicates how
1726                  many transactions  have  been  restarted  since  Mnesia  was
1727                  started.
1728
1729                * transaction_log_writes.  Returns a number that indicates how
1730                  many write operations that have been performed to the trans‐
1731                  action log since startup.
1732
1733                * use_dir.  Returns  a  boolean  that  indicates if the Mnesia
1734                  directory is used or not. Can be started even if  Mnesia  is
1735                  not yet running.
1736
1737                * version. Returns the current version number of Mnesia.
1738
1739       table(Tab [,[Option]]) -> QueryHandle
1740
1741              Returns  a  Query List Comprehension (QLC) query handle, see the
1742              qlc(3) manual page in STDLIB. The module qlc implements a  query
1743              language  that can use Mnesia tables as sources of data. Calling
1744              mnesia:table/1,2 is the means  to  make  the  mnesia  table  Tab
1745              usable to QLC.
1746
1747              Option  can contain Mnesia options or QLC options. Mnesia recog‐
1748              nizes the following options (any other option  is  forwarded  to
1749              QLC).
1750
1751                * {lock,  Lock},  where  lock can be read or write. Default is
1752                  read.
1753
1754                * {n_objects,Number}, where n_objects specifies (roughly)  the
1755                  number  of  objects  returned from Mnesia to QLC. Queries to
1756                  remote tables can need a  larger  chunk  to  reduce  network
1757                  overhead. By default, 100 objects at a time are returned.
1758
1759                * {traverse,  SelectMethod},  where  traverse  determines  the
1760                  method to traverse the whole table (if needed). The  default
1761                  method is select.
1762
1763              There are two alternatives for select:
1764
1765                * select.  The  table  is traversed by calling mnesia:select/4
1766                  and mnesia:select/1. The  match  specification  (the  second
1767                  argument  of  select/3)  is assembled by QLC: simple filters
1768                  are translated into equivalent  match  specifications.  More
1769                  complicated  filters  need  to  be  applied  to  all objects
1770                  returned  by  select/3  given  a  match  specification  that
1771                  matches all objects.
1772
1773                * {select,  MatchSpec}.  As for select, the table is traversed
1774                  by calling mnesia:select/3 and mnesia:select/1. The  differ‐
1775                  ence  is  that  the match specification is explicitly given.
1776                  This is how to state match specifications that cannot easily
1777                  be expressed within the syntax provided by QLC.
1778
1779       table_info(Tab, InfoKey) -> Info | exit({aborted, Reason})
1780
1781              The  table_info/2 function takes two arguments. The first is the
1782              name of a Mnesia table. The second is one of the following keys:
1783
1784                * all. Returns a list of all  local  table  information.  Each
1785                  element is a {InfoKey, ItemVal} tuple.
1786
1787                  New  InfoItems  can  be added and old undocumented InfoItems
1788                  can be removed without notice.
1789
1790                * access_mode. Returns the  access  mode  of  the  table.  The
1791                  access mode can be read_only or read_write.
1792
1793                * arity.  Returns  the arity of records in the table as speci‐
1794                  fied in the schema.
1795
1796                * attributes. Returns the table attribute names that are spec‐
1797                  ified in the schema.
1798
1799                * checkpoints.  Returns  the  names  of  the  currently active
1800                  checkpoints, which involve this table on this node.
1801
1802                * cookie. Returns a table cookie, which is  a  unique  system-
1803                  generated  identifier  for  the  table.  The  cookie is used
1804                  internally to ensure that two  different  table  definitions
1805                  using the same table name cannot accidentally be intermixed.
1806                  The cookie is generated when the table is created initially.
1807
1808                * disc_copies. Returns the nodes where a disc_copy of the  ta‐
1809                  ble resides according to the schema.
1810
1811                * disc_only_copies.  Returns  the nodes where a disc_only_copy
1812                  of the table resides according to the schema.
1813
1814                * index. Returns the list of index position integers  for  the
1815                  table.
1816
1817                * load_node.  Returns  the name of the node that Mnesia loaded
1818                  the table from. The  structure  of  the  returned  value  is
1819                  unspecified, but can be useful for debugging purposes.
1820
1821                * load_order. Returns the load order priority of the table. It
1822                  is an integer and defaults to 0 (zero).
1823
1824                * load_reason. Returns the reason of  why  Mnesia  decided  to
1825                  load  the  table.  The  structure  of  the returned value is
1826                  unspecified, but can be useful for debugging purposes.
1827
1828                * local_content. Returns true or false to indicate if the  ta‐
1829                  ble  is  configured  to  have locally unique content on each
1830                  node.
1831
1832                * master_nodes. Returns the master nodes of a table.
1833
1834                * memory. Returns the number of words allocated to  the  table
1835                  on this node.
1836
1837                * ram_copies.  Returns the nodes where a ram_copy of the table
1838                  resides according to the schema.
1839
1840                * record_name. Returns the record name, common for all records
1841                  in the table.
1842
1843                * size. Returns the number of records inserted in the table.
1844
1845                * snmp.  Returns the SNMP struct. [] means that the table cur‐
1846                  rently has no SNMP properties.
1847
1848                * storage_type. Returns the local storage type of  the  table.
1849                  It  can be disc_copies, ram_copies, disc_only_copies, or the
1850                  atom unknown. unknown is returned for all tables  that  only
1851                  reside remotely.
1852
1853                * subscribers.  Returns  a  list  of local processes currently
1854                  subscribing to local table events that involve this table on
1855                  this node.
1856
1857                * type.  Returns  the  table  type,  which  is  bag,  set,  or
1858                  ordered_set.
1859
1860                * user_properties. Returns the user-associated  table  proper‐
1861                  ties  of  the  table.  It  is  a list of the stored property
1862                  records.
1863
1864                * version. Returns the current version of  the  table  defini‐
1865                  tion.  The table version is incremented when the table defi‐
1866                  nition is changed. The table definition can  be  incremented
1867                  directly  when  it has been changed in a schema transaction,
1868                  or when a committed table definition is  merged  with  table
1869                  definitions from other nodes during startup.
1870
1871                * where_to_read. Returns the node where the table can be read.
1872                  If value nowhere is returned, either the table is not loaded
1873                  or it resides at a remote node that is not running.
1874
1875                * where_to_write.  Returns  a list of the nodes that currently
1876                  hold an active replica of the table.
1877
1878                * wild_pattern. Returns a structure that can be given  to  the
1879                  various  match functions for a certain table. A record tuple
1880                  is where all record fields have value '_'.
1881
1882       transaction(Fun [[, Args], Retries]) -> {aborted,  Reason}  |  {atomic,
1883       ResultOfFun}
1884
1885              Executes  the  functional  object  Fun  with arguments Args as a
1886              transaction.
1887
1888              The code that executes inside the transaction can consist  of  a
1889              series  of table manipulation functions. If something goes wrong
1890              inside the transaction as a result of a user error or a  certain
1891              table  not being available, the entire transaction is terminated
1892              and the function transaction/1 returns the tuple {aborted,  Rea‐
1893              son}.
1894
1895              If  all  is going well, {atomic, ResultOfFun} is returned, where
1896              ResultOfFun is the value of the last expression in Fun.
1897
1898              A function that adds a family to the database can be written  as
1899              follows  if  there is a structure {family, Father, Mother, Chil‐
1900              drenList}:
1901
1902              add_family({family, F, M, Children}) ->
1903                  ChildOids = lists:map(fun oid/1, Children),
1904                  Trans = fun() ->
1905                      mnesia:write(F#person{children = ChildOids},
1906                      mnesia:write(M#person{children = ChildOids},
1907                      Write = fun(Child) -> mnesia:write(Child) end,
1908                      lists:foreach(Write, Children)
1909                  end,
1910                  mnesia:transaction(Trans).
1911
1912              oid(Rec) -> {element(1, Rec), element(2, Rec)}.
1913
1914              This code adds a set of people to  the  database.  Running  this
1915              code within one transaction ensures that either the whole family
1916              is added to the database, or the whole  transaction  terminates.
1917              For  example,  if the last child is badly formatted, or the exe‐
1918              cuting process terminates because of an 'EXIT' signal while exe‐
1919              cuting  the  family  code, the transaction terminates. Thus, the
1920              situation where half a family is added can never occur.
1921
1922              It is also useful to update the database within a transaction if
1923              several  processes  concurrently  update  the  same records. For
1924              example, the function raise(Name, Amount), which adds Amount  to
1925              the salary field of a person, is to be implemented as follows:
1926
1927              raise(Name, Amount) ->
1928                  mnesia:transaction(fun() ->
1929                      case mnesia:wread({person, Name}) of
1930                          [P] ->
1931                              Salary = Amount + P#person.salary,
1932                              P2 = P#person{salary = Salary},
1933                              mnesia:write(P2);
1934                          _ ->
1935                              mnesia:abort("No such person")
1936                      end
1937                  end).
1938
1939              When  this  function executes within a transaction, several pro‐
1940              cesses running on different nodes can concurrently  execute  the
1941              function raise/2 without interfering with each other.
1942
1943              Since  Mnesia  detects deadlocks, a transaction can be restarted
1944              any number of times. This function attempts a restart as  speci‐
1945              fied  in  Retries.  Retries must be an integer greater than 0 or
1946              the atom infinity. Default is infinity.
1947
1948       transform_table(Tab, Fun, NewAttributeList, NewRecordName) -> {aborted,
1949       R} | {atomic, ok}
1950
1951              Applies argument Fun to all records in the table. Fun is a func‐
1952              tion that takes a record of the old type and  returns  a  trans‐
1953              formed record of the new type. Argument Fun can also be the atom
1954              ignore, which indicates that only the metadata about  the  table
1955              is  updated. Use of ignore is not recommended, but included as a
1956              possibility for the user do to an own transformation.
1957
1958              NewAttributeList and NewRecordName specify  the  attributes  and
1959              the  new  record  type of the converted table. Table name always
1960              remains unchanged. If record_name is changed,  only  the  Mnesia
1961              functions  that  use  table  identifiers work, for example, mne‐
1962              sia:write/3 works, but not mnesia:write/1.
1963
1964       transform_table(Tab, Fun, NewAttributeList) -> {aborted, R} |  {atomic,
1965       ok}
1966
1967              Calls  mnesia:transform_table(Tab,  Fun,  NewAttributeList, Rec‐
1968              Name), where RecName is mnesia:table_info(Tab, record_name).
1969
1970       traverse_backup(Source, [SourceMod,] Target, [TargetMod,] Fun, Acc)  ->
1971       {ok, LastAcc} | {error, Reason}
1972
1973              Iterates  over  a  backup,  either  to  transform  it into a new
1974              backup, or read it. The arguments are  explained  briefly  here.
1975              For details, see the User's Guide.
1976
1977                * SourceMod  and  TargetMod  are the names of the modules that
1978                  actually access the backup media.
1979
1980                * Source and Target are opaque data used exclusively  by  mod‐
1981                  ules SourceMod and TargetMod to initialize the backup media.
1982
1983                * Acc is an initial accumulator value.
1984
1985                * Fun(BackupItems, Acc) is applied to each item in the backup.
1986                  The Fun must  return  a  tuple  {BackupItems,NewAcc},  where
1987                  BackupItems is a list of valid backup items, and NewAcc is a
1988                  new accumulator value. The returned backup items are written
1989                  in the target backup.
1990
1991                * LastAcc  is  the  last  accumulator  value. This is the last
1992                  NewAcc value that was returned by Fun.
1993
1994       uninstall_fallback() -> ok | {error,Reason}
1995
1996              Calls the function mnesia:uninstall_fallback([{scope, global}]).
1997
1998       uninstall_fallback(Args) -> ok | {error,Reason}
1999
2000              Deinstalls a fallback before it has been  used  to  restore  the
2001              database.  This  is  normally  a  distributed  operation that is
2002              either performed on all nodes  with  disc  resident  schema,  or
2003              none.  Uninstallation  of fallbacks requires Erlang to be opera‐
2004              tional on all involved nodes, but it does not matter  if  Mnesia
2005              is running or not. Which nodes that are considered as disc-resi‐
2006              dent nodes is determined from  the  schema  information  in  the
2007              local fallback.
2008
2009              Args is a list of the following tuples:
2010
2011                * {module, BackupMod}. For semantics, see mnesia:install_fall‐
2012                  back/2.
2013
2014                * {scope,  Scope}.  For  semantics,  see  mnesia:install_fall‐
2015                  back/2.
2016
2017                * {mnesia_dir,   AlternateDir}.   For   semantics,   see  mne‐
2018                  sia:install_fallback/2.
2019
2020       unsubscribe(EventCategory) -> {ok, Node} | {error, Reason}
2021
2022              Stops sending events of type EventCategory to the caller.
2023
2024              Node is the local node.
2025
2026       wait_for_tables(TabList, Timeout)  ->  ok  |  {timeout,  BadTabList}  |
2027       {error, Reason}
2028
2029              Some applications need to wait for certain tables to be accessi‐
2030              ble to do useful  work.  mnesia:wait_for_tables/2  either  hangs
2031              until  all tables in TabList are accessible, or until timeout is
2032              reached.
2033
2034       wread({Tab, Key}) -> transaction abort | RecordList
2035
2036              Calls the function mnesia:read(Tab, Key, write).
2037
2038       write(Record) -> transaction abort | ok
2039
2040              Calls the function mnesia:write(Tab, Record, write),  where  Tab
2041              is element(1, Record).
2042
2043       write(Tab, Record, LockKind) -> transaction abort | ok
2044
2045              Writes record Record to table Tab.
2046
2047              The  function  returns ok, or terminates if an error occurs. For
2048              example, the transaction terminates if no person table exists.
2049
2050              The  semantics  of  this  function  is  context-sensitive.   For
2051              details,   see  mnesia:activity/4.  In  transaction-context,  it
2052              acquires a lock of type  LockKind.  The  lock  types  write  and
2053              sticky_write are supported.
2054
2055       write_lock_table(Tab) -> ok | transaction abort
2056
2057              Calls the function mnesia:lock({table, Tab}, write).
2058

CONFIGURATION PARAMETERS

2060       Mnesia reads the following application configuration parameters:
2061
2062         * -mnesia  access_module  Module.  The  name  of  the Mnesia activity
2063           access callback module. Default is mnesia.
2064
2065         * -mnesia auto_repair true | false.  This  flag  controls  if  Mnesia
2066           automatically  tries  to  repair  files that have not been properly
2067           closed. Default is true.
2068
2069         * -mnesia backup_module Module. The name of the Mnesia  backup  call‐
2070           back module. Default is mnesia_backup.
2071
2072         * -mnesia debug Level. Controls the debug level of Mnesia. The possi‐
2073           ble values are as follows:
2074
2075           none:
2076             No trace outputs. This is the default.
2077
2078           verbose:
2079             Activates tracing of important debug events. These events  gener‐
2080             ate {mnesia_info, Format, Args} system events. Processes can sub‐
2081             scribe to these events with mnesia:subscribe/1.  The  events  are
2082             always sent to the Mnesia event handler.
2083
2084           debug:
2085             Activates  all events at the verbose level plus full trace of all
2086             debug events. These debug events generate  {mnesia_info,  Format,
2087             Args} system events. Processes can subscribe to these events with
2088             mnesia:subscribe/1. The events are  always  sent  to  the  Mnesia
2089             event  handler.  On  this  debug  level, the Mnesia event handler
2090             starts subscribing to updates in the schema table.
2091
2092           trace:
2093             Activates all events at the debug level. On this level, the  Mne‐
2094             sia  event  handler  starts  subscribing to updates on all Mnesia
2095             tables. This level is intended only for debugging small toy  sys‐
2096             tems, as many large events can be generated.
2097
2098           false:
2099             An alias for none.
2100
2101           true:
2102             An alias for debug.
2103
2104         * -mnesia  core_dir Directory. The name of the directory where Mnesia
2105           core files is stored, or false. Setting it implies that  also  RAM-
2106           only nodes generate a core file if a crash occurs.
2107
2108         * -mnesia dc_dump_limit Number. Controls how often disc_copies tables
2109           are dumped from memory. Tables  are  dumped  when  filesize(Log)  >
2110           (filesize(Tab)/Dc_dump_limit). Lower values reduce CPU overhead but
2111           increase disk space and startup times. Default is 4.
2112
2113         * -mnesia dir Directory. The name of the directory where  all  Mnesia
2114           data  is  stored. The directory name must be unique for the current
2115           node. Two nodes must never share the the same Mnesia directory. The
2116           results are unpredictable.
2117
2118         * -mnesia  dump_disc_copies_at_startup true | false. If set to false,
2119           this disables the dumping  of  disc_copies  tables  during  startup
2120           while tables are being loaded. The default is true.
2121
2122         * -mnesia  dump_log_load_regulation  true  |  false.  Controls if log
2123           dumps are to be performed as fast as possible, or if the dumper  is
2124           to do its own load regulation. Default is false.
2125
2126           This feature is temporary and will be removed in a future release
2127
2128         * -mnesia  dump_log_update_in_place  true  |  false.  Controls if log
2129           dumps are performed on a copy of the original data file, or if  the
2130           log dump is performed on the original data file. Default is true
2131
2132         *
2133
2134
2135           -mnesia dump_log_write_threshold Max. Max is an integer that speci‐
2136           fies the maximum number of writes allowed to  the  transaction  log
2137           before  a  new  dump  of  the  log is performed. Default is 100 log
2138           writes.
2139
2140         *
2141
2142
2143           -mnesia dump_log_time_threshold Max. Max is an integer that  speci‐
2144           fies  the  dump log interval in milliseconds. Default is 3 minutes.
2145           If a dump has not  been  performed  within  dump_log_time_threshold
2146           milliseconds,  a  new dump is performed regardless of the number of
2147           writes performed.
2148
2149         * -mnesia event_module Module. The name of the Mnesia  event  handler
2150           callback module. Default is mnesia_event.
2151
2152         * -mnesia extra_db_nodes Nodes specifies a list of nodes, in addition
2153           to the ones found in the schema,  with  which  Mnesia  is  also  to
2154           establish contact. Default is [] (empty list).
2155
2156         * -mnesia fallback_error_function {UserModule, UserFunc}. Specifies a
2157           user-supplied callback function, which is called if a  fallback  is
2158           installed  and  Mnesia  goes down on another node. Mnesia calls the
2159           function with one argument, the name of the dying node,  for  exam‐
2160           ple, UserModule:UserFunc(DyingNode). Mnesia must be restarted, oth‐
2161           erwise the database can be inconsistent. The default behavior is to
2162           terminate Mnesia.
2163
2164         * -mnesia  max_wait_for_decision  Timeout.  Specifies how long Mnesia
2165           waits for other nodes to share their knowledge about the outcome of
2166           an  unclear  transaction.  By  default,  Timeout is set to the atom
2167           infinity. This implies  that  if  Mnesia  upon  startup  detects  a
2168           "heavyweight  transaction" whose outcome is unclear, the local Mne‐
2169           sia waits until Mnesia is started on some (in the worst  case  all)
2170           of  the  other nodes that were involved in the interrupted transac‐
2171           tion. This is a rare situation, but if it occurs, Mnesia  does  not
2172           guess if the transaction on the other nodes was committed or termi‐
2173           nated. Mnesia waits until  it  knows  the  outcome  and  then  acts
2174           accordingly.
2175
2176           If  Timeout  is  set  to  an  integer value in milliseconds, Mnesia
2177           forces "heavyweight transactions" to be finished, even if the  out‐
2178           come  of  the  transaction for the moment is unclear. After Timeout
2179           milliseconds, Mnesia commits or terminates the transaction and con‐
2180           tinues  with  the  startup.  This can lead to a situation where the
2181           transaction is committed on some  nodes  and  terminated  on  other
2182           nodes.  If  the  transaction is a schema transaction, the inconsis‐
2183           tency can be fatal.
2184
2185         * -mnesia no_table_loaders NUMBER. Specifies the number  of  parallel
2186           table loaders during start. More loaders can be good if the network
2187           latency is high or if many tables contain few records.  Default  is
2188           2.
2189
2190         * -mnesia  send_compressed  Level. Specifies the level of compression
2191           to be used when copying a table from the local node to another one.
2192           Default is 0.
2193
2194           Level  must  be an integer in the interval [0, 9], where 0 means no
2195           compression and 9 means maximum compression. Before setting it to a
2196           non-zero  value,  ensure that the remote nodes understand this con‐
2197           figuration.
2198
2199         * -mnesia schema_location Loc. Controls where Mnesia  looks  for  its
2200           schema. Parameter Loc can be one of the following atoms:
2201
2202           disc:
2203             Mandatory disc. The schema is assumed to be located in the Mnesia
2204             directory. If the schema  cannot  be  found,  Mnesia  refuses  to
2205             start. This is the old behavior.
2206
2207           ram:
2208             Mandatory RAM. The schema resides in RAM only. At startup, a tiny
2209             new schema is generated. This default schema  only  contains  the
2210             definition  of  the  schema  table  and only resides on the local
2211             node. Since no other nodes are found in the default schema,  con‐
2212             figuration  parameter extra_db_nodes must be used to let the node
2213             share its table definitions with other nodes.
2214
2215             Parameter extra_db_nodes can also be used on disc based nodes.
2216
2217           opt_disc:
2218             Optional disc. The schema can reside on disc or in  RAM.  If  the
2219             schema  is  found on disc, Mnesia starts as a disc-based node and
2220             the storage type of the schema table is disc_copies. If no schema
2221             is found on disc, Mnesia starts as a disc-less node and the stor‐
2222             age type of the schema table is ram_copies. Default value for the
2223             application parameter is opt_disc.
2224
2225       First,  the  SASL application parameters are checked, then the command-
2226       line flags are checked, and finally, the default value is chosen.
2227

SEE ALSO

2229       application(3),  dets(3),  disk_log(3),   ets(3),   mnesia_registry(3),
2230       qlc(3)
2231
2232
2233
2234Ericsson AB                      mnesia 4.15.6                       mnesia(3)
Impressum