1mnesia(3) Erlang Module Definition mnesia(3)
2
6 mnesia - A distributed telecommunications DBMS
7
9 The following are some of the most important and attractive capabili‐
10 ties provided by Mnesia:
11 * A relational/object hybrid data model that is suitable for telecom‐
13 munications applications.
14 * A DBMS query language, Query List Comprehension (QLC) as an add-on
16 library.
17 * Persistence. Tables can be coherently kept on disc and in the main
19 memory.
20 * Replication. Tables can be replicated at several nodes.
22 * Atomic transactions. A series of table manipulation operations can
24 be grouped into a single atomic transaction.
25 * Location transparency. Programs can be written without knowledge of
27 the actual data location.
28 * Extremely fast real-time data searches.
30 * Schema manipulation routines. The DBMS can be reconfigured at run‐
32 time without stopping the system.
33 This Reference Manual describes the Mnesia API. This includes functions
35 that define and manipulate Mnesia tables.
36 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 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 * 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 If a table is of type set, each key leads to either one or zero
52 records.
53 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 * 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 * 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 * 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 * 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 * 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 * 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 * 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 * 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 * attributes. The names of the attributes for the records that are
101 inserted in the table.
102 For information about the complete set of table properties and their
104 details, see mnesia:create_table/2.
105 This Reference Manual uses a table of persons to illustrate various
107 examples. The following record definition is assumed:
108 -record(person, {name,
110 age = 0,
111 address = unknown,
112 salary = 0,
113 children = []}),
114 The first record attribute is the primary key, or key for short.
116 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 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 If possible, avoid writing or deleting records in the same transaction
128 before iterating over the table.
129
131 abort(Reason) -> transaction abort
132 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 activate_checkpoint(Args) -> {ok,Name,Nodes} | {error,Reason}
139 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 Args is a list of the following tuples:
147 * {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 * {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 * {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 * {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 * {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 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 activity(AccessContext, Fun [, Args]) -> ResultOfFun | exit(Reason)
189 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 activity(AccessContext, Fun, Args, AccessMod) -> ResultOfFun |
196 exit(Reason)
197 Executes the functional object Fun with argument Args.
199 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 transaction:
206 Short for {transaction, infinity}
207 {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 sync_transaction:
215 Short for {sync_transaction, infinity}
216 {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 async_dirty:
224 Calls mnesia:async_dirty(Fun, Args).
225 sync_dirty:
227 Calls mnesia:sync_dirty(Fun, Args).
228 ets:
230 Calls mnesia:ets(Fun, Args).
231 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 Mnesia forwards calls to the following functions:
239 * mnesia:lock/2 (read_lock_table/1, write_lock_table/1)
241 * mnesia:write/3 (write/1, s_write/1)
243 * mnesia:delete/3 (delete/1, s_delete/1)
245 * mnesia:delete_object/3 (delete_object/1, s_delete_object/1)
247 * mnesia:read/3 (read/1, wread/1)
249 * mnesia:match_object/3 (match_object/1)
251 * mnesia:all_keys/1
253 * mnesia:first/1
255 * mnesia:last/1
257 * mnesia:prev/2
259 * mnesia:next/2
261 * mnesia:index_match_object/4 (index_match_object/2)
263 * mnesia:index_read/3
265 * mnesia:table_info/2
267 to the corresponding:
269 * AccessMod:lock(ActivityId, Opaque, LockItem, LockKind)
271 * AccessMod:write(ActivityId, Opaque, Tab, Rec, LockKind)
273 * AccessMod:delete(ActivityId, Opaque, Tab, Key, LockKind)
275 * AccessMod:delete_object(ActivityId, Opaque, Tab, RecXS,
277 LockKind)
278 * AccessMod:read(ActivityId, Opaque, Tab, Key, LockKind)
280 * AccessMod:match_object(ActivityId, Opaque, Tab, Pattern,
282 LockKind)
283 * AccessMod:all_keys(ActivityId, Opaque, Tab, LockKind)
285 * AccessMod:first(ActivityId, Opaque, Tab)
287 * AccessMod:last(ActivityId, Opaque, Tab)
289 * AccessMod:prev(ActivityId, Opaque, Tab, Key)
291 * AccessMod:next(ActivityId, Opaque, Tab, Key)
293 * AccessMod:index_match_object(ActivityId, Opaque, Tab, Pat‐
295 tern, Attr, LockKind)
296 * AccessMod:index_read(ActivityId, Opaque, Tab, SecondaryKey,
298 Attr, LockKind)
299 * AccessMod:table_info(ActivityId, Opaque, Tab, InfoItem)
301 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 Opaque is an opaque data structure that is internal to Mnesia.
310 add_table_copy(Tab, Node, Type) -> {aborted, R} | {atomic, ok}
312 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 mnesia:add_table_copy(person, Node, disc_copies)
319 This function can also be used to add a replica of the table
321 named schema.
322 add_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}
324 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 mnesia:add_table_index(person, age)
334 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 all_keys(Tab) -> KeyList | transaction abort
340 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 async_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason)
347 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 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 Notice that it is more than ten times more efficient to read
368 records dirty than within a transaction.
369 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 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 Notice that calling (nesting) mnesia:[a]sync_dirty inside a
381 transaction-context inherits the transaction semantics.
382 backup(Opaque [, BackupMod]) -> ok | {error,Reason}
384 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 backup_checkpoint(Name, Opaque [, BackupMod]) -> ok | {error,Reason}
392 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 change_config(Config, Value) -> {error, Reason} | {ok, ReturnValue}
402 Config is to be an atom of the following configuration parame‐
404 ters:
405 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 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 Notice that Mnesia can be connected to other nodes than
417 those returned in ReturnValue.
418 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 change_table_access_mode(Tab, AccessMode) -> {aborted, R} | {atomic,
426 ok}
427 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 change_table_copy_type(Tab, Node, To) -> {aborted, R} | {atomic, ok}
435 For example:
437 mnesia:change_table_copy_type(person, node(), disc_copies)
439 Transforms the person table from a RAM table into a disc-based
441 table at Node.
442 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 change_table_load_order(Tab, LoadOrder) -> {aborted, R} | {atomic, ok}
450 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 change_table_majority(Tab, Majority) -> {aborted, R} | {atomic, ok}
456 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 clear_table(Tab) -> {aborted, R} | {atomic, ok}
464 Deletes all entries in the table Tab.
466 create_schema(DiscNodes) -> ok | {error,Reason}
468 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 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 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 create_table(Name, TabDef) -> {atomic, ok} | {aborted, Reason}
485 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 * {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 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 * {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 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 * {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 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 * {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 * {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 * {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 * {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 * {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 * {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 * {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 * {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 For example:
571 mnesia:create_table(table, [{ram_copies, [node()]}, {disc_only_copies, nodes()},
573 {storage_properties,
574 [{ets, [compressed]}, {dets, [{auto_save, 5000}]} ]}])
575 * {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 Notice that currently ordered_set is not supported for
584 disc_only_copies.
585 * {local_content, Bool}, where Bool is true or false. Default
587 is false.
588 For example, the following call creates the person table
590 (defined earlier) and replicates it on two nodes:
591 mnesia:create_table(person,
593 [{ram_copies, [N1, N2]},
594 {attributes, record_info(fields, person)}]).
595 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 mnesia:create_table(person,
601 [{ram_copies, [N1, N2]},
602 {index, [address]},
603 {attributes, record_info(fields, person)}]).
604 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 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 deactivate_checkpoint(Name) -> ok | {error, Reason}
617 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 del_table_copy(Tab, Node) -> {aborted, R} | {atomic, ok}
625 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 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 del_table_index(Tab, AttrName) -> {aborted, R} | {atomic, ok}
635 Deletes the index on attribute with name AttrName in a table.
637 delete({Tab, Key}) -> transaction abort | ok
639 Calls mnesia:delete(Tab, Key, write).
641 delete(Tab, Key, LockKind) -> transaction abort | ok
643 Deletes all records in table Tab with the key Key.
645 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 delete_object(Record) -> transaction abort | ok
652 Calls mnesia:delete_object(Tab, Record, write), where Tab is
654 element(1, Record).
655 delete_object(Tab, Record, LockKind) -> transaction abort | ok
657 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 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 delete_schema(DiscNodes) -> ok | {error,Reason}
669 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 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 Warning:
680 Use this function with extreme caution, as it makes existing
681 persistent data obsolete. Think twice before using it.
682 delete_table(Tab) -> {aborted, Reason} | {atomic, ok}
685 Permanently deletes all replicas of table Tab.
687 dirty_all_keys(Tab) -> KeyList | exit({aborted, Reason})
689 Dirty equivalent of the function mnesia:all_keys/1.
691 dirty_delete({Tab, Key}) -> ok | exit({aborted, Reason})
693 Calls mnesia:dirty_delete(Tab, Key).
695 dirty_delete(Tab, Key) -> ok | exit({aborted, Reason})
697 Dirty equivalent of the function mnesia:delete/3.
699 dirty_delete_object(Record)
701 Calls mnesia:dirty_delete_object(Tab, Record), where Tab is ele‐
703 ment(1, Record).
704 dirty_delete_object(Tab, Record)
706 Dirty equivalent of the function mnesia:delete_object/3.
708 dirty_first(Tab) -> Key | exit({aborted, Reason})
710 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 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 dirty_index_match_object(Pattern, Pos)
722 Starts mnesia:dirty_index_match_object(Tab, Pattern, Pos), where
724 Tab is element(1, Pattern).
725 dirty_index_match_object(Tab, Pattern, Pos)
727 Dirty equivalent of the function mnesia:index_match_object/4.
729 dirty_index_read(Tab, SecondaryKey, Pos)
731 Dirty equivalent of the function mnesia:index_read/3.
733 dirty_last(Tab) -> Key | exit({aborted, Reason})
735 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 dirty_match_object(Pattern) -> RecordList | exit({aborted, Reason})
742 Calls mnesia:dirty_match_object(Tab, Pattern), where Tab is ele‐
744 ment(1, Pattern).
745 dirty_match_object(Tab, Pattern) -> RecordList | exit({aborted, Rea‐
747 son})
748 Dirty equivalent of the function mnesia:match_object/3.
750 dirty_next(Tab, Key) -> Key | exit({aborted, Reason})
752 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 dirty_prev(Tab, Key) -> Key | exit({aborted, Reason})
762 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 dirty_read({Tab, Key}) -> ValueList | exit({aborted, Reason}
769 Calls mnesia:dirty_read(Tab, Key).
771 dirty_read(Tab, Key) -> ValueList | exit({aborted, Reason}
773 Dirty equivalent of the function mnesia:read/3.
775 dirty_select(Tab, MatchSpec) -> ValueList | exit({aborted, Reason}
777 Dirty equivalent of the function mnesia:select/2.
779 dirty_slot(Tab, Slot) -> RecordList | exit({aborted, Reason})
781 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 dirty_update_counter({Tab, Key}, Incr) -> NewVal | exit({aborted, Rea‐
791 son})
792 Calls mnesia:dirty_update_counter(Tab, Key, Incr).
794 dirty_update_counter(Tab, Key, Incr) -> NewVal | exit({aborted, Rea‐
796 son})
797 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 * It is much more efficient.
807 * mnesia:dirty_update_counter/3 is performed as an atomic
809 operation although it is not protected by a transaction.
810 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 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 dirty_write(Record) -> ok | exit({aborted, Reason})
819 Calls mnesia:dirty_write(Tab, Record), where Tab is element(1,
821 Record).
822 dirty_write(Tab, Record) -> ok | exit({aborted, Reason})
824 Dirty equivalent of the function mnesia:write/3.
826 dump_log() -> dumped
828 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 dump_tables(TabList) -> {atomic, ok} | {aborted, Reason}
835 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 dump_to_textfile(Filename)
842 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 error_description(Error) -> String
850 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 * nested_transaction. Nested transactions are not allowed in
858 this context.
859 * badarg. Bad or invalid argument, possibly bad type.
861 * no_transaction. Operation not allowed outside transactions.
863 * combine_error. Table options illegally combined.
865 * bad_index. Index already exists, or was out of bounds.
867 * already_exists. Schema option to be activated is already on.
869 * index_exists. Some operations cannot be performed on tables
871 with an index.
872 * no_exists. Tried to perform operation on non-existing (not-
874 alive) item.
875 * system_limit. A system limit was exhausted.
877 * 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 * not_a_db_node. A node was mentioned that does not exist in
884 the schema.
885 * bad_type. Bad type specified in argument.
887 * node_not_running. Node is not running.
889 * truncated_binary_file. Truncated binary in file.
891 * active. Some delete operations require that all active
893 records are removed.
894 * illegal. Operation not supported on this record.
896 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 The following examples illustrate a function that returns an
902 error, and the method to retrieve more detailed error informa‐
903 tion:
904 * 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 * 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 ets(Fun, [, Args]) -> ResultOfFun | exit(Reason)
914 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 Notice that calling (nesting) a mnesia:ets inside a transaction-
926 context inherits the transaction semantics.
927 first(Tab) -> Key | transaction abort
929 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 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 foldl(Function, Acc, Table) -> NewAcc | transaction abort
941 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 foldl returns the same term as the last call to Function
947 returned.
948 foldr(Function, Acc, Table) -> NewAcc | transaction abort
950 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 force_load_table(Tab) -> yes | ErrorDescription
956 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 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 index_match_object(Pattern, Pos) -> transaction abort | ObjList
971 Starts mnesia:index_match_object(Tab, Pattern, Pos, read), where
973 Tab is element(1, Pattern).
974 index_match_object(Tab, Pattern, Pos, LockKind) -> transaction abort |
976 ObjList
977 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 * The table Tab must have an index on position Pos.
985 * The element in position Pos in Pattern must be bound. Pos is
987 an integer (#record.Field) or an attribute name.
988 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 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 index_read(Tab, SecondaryKey, Pos) -> transaction abort | RecordList
1000 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 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 info() -> ok
1015 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 install_fallback(Opaque) -> ok | {error,Reason}
1021 Calls mnesia:install_fallback(Opaque, Args), where Args is
1023 [{scope, global}].
1024 install_fallback(Opaque), BackupMod) -> ok | {error,Reason}
1026 Calls mnesia:install_fallback(Opaque, Args), where Args is
1028 [{scope, global}, {module, BackupMod}].
1029 install_fallback(Opaque, Args) -> ok | {error,Reason}
1031 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 Args is a list of the following tuples:
1040 * {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 * {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 If Scope of the operation is local, the fallback is only
1058 installed on the local node.
1059 * {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 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 is_transaction() -> boolean
1076 When this function is executed inside a transaction-context, it
1078 returns true, otherwise false.
1079 last(Tab) -> Key | transaction abort
1081 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 load_textfile(Filename)
1088 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 lock(LockItem, LockKind) -> Nodes | ok | transaction abort
1096 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 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 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 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 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 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 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 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 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 Currently, this function supports two kinds of LockItem:
1153 {table, Tab}:
1155 This acquires a lock of type LockKind on the entire table
1156 Tab.
1157 {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 Locks are released when the outermost transaction ends.
1164 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 match_object(Pattern) -> transaction abort | RecList
1170 Calls mnesia:match_object(Tab, Pattern, read), where Tab is ele‐
1172 ment(1, Pattern).
1173 match_object(Tab, Pattern, LockKind) -> transaction abort | RecList
1175 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 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 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 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 move_table_copy(Tab, From, To) -> {aborted, Reason} | {atomic, ok}
1196 Moves the copy of table Tab from node From to node To.
1198 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 This function cannot be used on local_content tables.
1204 next(Tab, Key) -> Key | transaction abort
1206 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 prev(Tab, Key) -> Key | transaction abort
1213 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 read({Tab, Key}) -> transaction abort | RecordList
1220 Calls function mnesia:read(Tab, Key, read).
1222 read(Tab, Key) -> transaction abort | RecordList
1224 Calls function mnesia:read(Tab, Key, read).
1226 read(Tab, Key, LockKind) -> transaction abort | RecordList
1228 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 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 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 read_lock_table(Tab) -> ok | transaction abort
1247 Calls the function mnesia:lock({table, Tab}, read).
1249 report_event(Event) -> ok
1251 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 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 restore(Opaque, Args) -> {atomic, RestoredTabs} |{aborted, Reason}
1263 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 * {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 * {skip_tables, TabList}, where TabList is a list of tables
1273 that is not to be read from the backup.
1274 * {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 * {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 * {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 * {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 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 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 s_delete({Tab, Key}) -> ok | transaction abort
1311 Calls the function mnesia:delete(Tab, Key, sticky_write)
1313 s_delete_object(Record) -> ok | transaction abort
1315 Calls the function mnesia:delete_object(Tab, Record,
1317 sticky_write), where Tab is element(1, Record).
1318 s_write(Record) -> ok | transaction abort
1320 Calls the function mnesia:write(Tab, Record, sticky_write),
1322 where Tab is element(1, Record).
1323 schema() -> ok
1325 Prints information about all table definitions on the terminal.
1327 schema(Tab) -> ok
1329 Prints information about one table definition on the terminal.
1331 select(Tab, MatchSpec [, Lock]) -> transaction abort | [Object]
1333 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 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 In its simplest forms, the match_spec look as follows:
1345 * MatchSpec = [MatchFunction]
1347 * MatchFunction = {MatchHead, [Guard], [Result]}
1349 * MatchHead = tuple() | record()
1351 * Guard = {"Guardtest name", ...}
1353 * Result = "Term construct"
1355 For a complete description of select, see the ERTS User's Guide
1357 and the ets manual page in STDLIB.
1358 For example, to find the names of all male persons older than 30
1360 in table Tab:
1361 MatchHead = #person{name='$1', sex=male, age='$2', _='_'},
1363 Guard = {'>', '$2', 30},
1364 Result = '$1',
1365 mnesia:select(Tab,[{MatchHead, [Guard], [Result]}]),
1366 select(Tab, MatchSpec, NObjects, Lock) -> transaction abort |
1368 {[Object],Cont} | '$end_of_table'
1369 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 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 select(Cont) -> transaction abort | {[Object],Cont} | '$end_of_table'
1385 Selects more objects with the match specification initiated by
1387 mnesia:select/4.
1388 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 set_debug_level(Level) -> OldLevel
1394 Changes the internal debug level of Mnesia. For details, see
1396 Section Configuration Parameters.
1397 set_master_nodes(MasterNodes) -> ok | {error, Reason}
1399 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 set_master_nodes(Tab, MasterNodes) -> ok | {error, Reason}
1406 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 The master node setting is always local. It can be changed
1421 regardless if Mnesia is started or not.
1422 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 snmp_close_table(Tab) -> {aborted, R} | {atomic, ok}
1428 Removes the possibility for SNMP to manipulate the table.
1430 snmp_get_mnesia_key(Tab, RowIndex) -> {ok, Key} | undefined
1432 Types:
1434 Tab ::= atom()
1436 RowIndex ::= [integer()]
1437 Key ::= key() | {key(), key(), ...}
1438 key() ::= integer() | string() | [integer()]
1439 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 snmp_get_next_index(Tab, RowIndex) -> {ok, NextIndex} | endOfTable
1445 Types:
1447 Tab ::= atom()
1449 RowIndex ::= [integer()]
1450 NextIndex ::= [integer()]
1451 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 snmp_get_row(Tab, RowIndex) -> {ok, Row} | undefined
1458 Types:
1460 Tab ::= atom()
1462 RowIndex ::= [integer()]
1463 Row ::= record(Tab)
1464 Reads a row by its SNMP index. This index is specified as an
1466 SNMP Object Identifier, a list of integers.
1467 snmp_open_table(Tab, SnmpStruct) -> {aborted, R} | {atomic, ok}
1469 Types:
1471 Tab ::= atom()
1473 SnmpStruct ::= [{key, type()}]
1474 type() ::= type_spec() | {type_spec(), type_spec(), ...}
1475 type_spec() ::= fix_string | string | integer
1476 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 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 For example, the following causes table person to be ordered as
1494 an SNMP table:
1495 mnesia:snmp_open_table(person, [{key, string}])
1497 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 mnesia:create_table(employee,
1503 [{snmp, [{key, {integer, string}}]},
1504 {attributes, record_info(fields, employees)}]),
1505 The corresponding SNMP table would have three columns: depart‐
1507 ment, name, and telno.
1508 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 In a table monitored by SNMP, all elements must be integers,
1517 strings, or lists of integers.
1518 When a table is SNMP ordered, modifications are more expensive
1520 than usual, O(logN). Also, more memory is used.
1521 Notice that only the lexicographical SNMP ordering is imple‐
1523 mented in Mnesia, not the actual SNMP monitoring.
1524 start() -> ok | {error, Reason}
1526 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 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 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 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 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 application:start(mnesia) can also be used.
1563 stop() -> stopped
1565 Stops Mnesia locally on the current node.
1567 application:stop(mnesia) can also be used.
1569 subscribe(EventCategory) -> {ok, Node} | {error, Reason}
1571 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 sync_dirty(Fun, [, Args]) -> ResultOfFun | exit(Reason)
1577 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 sync_log() -> ok | {error, Reason}
1588 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 sync_transaction(Fun, [[, Args], Retries]) -> {aborted, Reason} |
1595 {atomic, ResultOfFun}
1596 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 This functionality can be used to avoid that one process over‐
1602 loads a database on another node.
1603 system_info(InfoKey) -> Info | exit({aborted, Reason})
1605 Returns information about the Mnesia system, such as transaction
1607 statistics, db_nodes, and configuration parameters. The valid
1608 keys are as follows:
1609 * all. Returns a list of all local system information. Each
1611 element is a {InfoKey, InfoVal} tuple.
1612 New InfoKeys can be added and old undocumented InfoKeys can
1614 be removed without notice.
1615 * access_module. Returns the name of module that is configured
1617 to be the activity access callback module.
1618 * 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 * backup_module. Returns the name of the module that is con‐
1624 figured to be the backup callback module.
1625 * checkpoints. Returns a list of the names of the checkpoints
1627 currently active on this node.
1628 * event_module. Returns the name of the module that is the
1630 event handler callback module.
1631 * 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 * debug. Returns the current debug level of Mnesia.
1639 * directory. Returns the name of the Mnesia directory. It can
1641 be called even if Mnesia is not yet running.
1642 * dump_log_load_regulation. Returns a boolean that tells if
1644 Mnesia is configured to regulate the dumper process load.
1645 This feature is temporary and will be removed in future
1647 releases.
1648 * dump_log_time_threshold. Returns the time threshold for
1650 transaction log dumps in milliseconds.
1651 * 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 * 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 * extra_db_nodes. Returns a list of extra db_nodes to be con‐
1662 tacted at startup.
1663 * fallback_activated. Returns true if a fallback is activated,
1665 otherwise false.
1666 * held_locks. Returns a list of all locks held by the local
1668 Mnesia lock manager.
1669 * 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 * local_tables. Returns a list of all tables that are config‐
1675 ured to reside locally.
1676 * lock_queue. Returns a list of all transactions that are
1678 queued for execution by the local lock manager.
1679 * log_version. Returns the version number of the Mnesia trans‐
1681 action log format.
1682 * master_node_tables. Returns a list of all tables with at
1684 least one master node.
1685 * protocol_version. Returns the version number of the Mnesia
1687 inter-process communication protocol.
1688 * 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 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 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 * schema_location. Returns the initial schema location.
1709 * subscribers. Returns a list of local processes currently
1711 subscribing to system events.
1712 * tables. Returns a list of all locally known tables.
1714 * transactions. Returns a list of all currently active local
1716 transactions.
1717 * transaction_failures. Returns a number that indicates how
1719 many transactions have failed since Mnesia was started.
1720 * transaction_commits. Returns a number that indicates how
1722 many transactions have terminated successfully since Mnesia
1723 was started.
1724 * transaction_restarts. Returns a number that indicates how
1726 many transactions have been restarted since Mnesia was
1727 started.
1728 * 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 * 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 * version. Returns the current version number of Mnesia.
1738 table(Tab [,[Option]]) -> QueryHandle
1740 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 Option can contain Mnesia options or QLC options. Mnesia recog‐
1748 nizes the following options (any other option is forwarded to
1749 QLC).
1750 * {lock, Lock}, where lock can be read or write. Default is
1752 read.
1753 * {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 * {traverse, SelectMethod}, where traverse determines the
1760 method to traverse the whole table (if needed). The default
1761 method is select.
1762 There are two alternatives for select:
1764 * 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 * {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 table_info(Tab, InfoKey) -> Info | exit({aborted, Reason})
1780 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 * all. Returns a list of all local table information. Each
1785 element is a {InfoKey, ItemVal} tuple.
1786 New InfoItems can be added and old undocumented InfoItems
1788 can be removed without notice.
1789 * access_mode. Returns the access mode of the table. The
1791 access mode can be read_only or read_write.
1792 * arity. Returns the arity of records in the table as speci‐
1794 fied in the schema.
1795 * attributes. Returns the table attribute names that are spec‐
1797 ified in the schema.
1798 * checkpoints. Returns the names of the currently active
1800 checkpoints, which involve this table on this node.
1801 * 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 * disc_copies. Returns the nodes where a disc_copy of the ta‐
1809 ble resides according to the schema.
1810 * disc_only_copies. Returns the nodes where a disc_only_copy
1812 of the table resides according to the schema.
1813 * index. Returns the list of index position integers for the
1815 table.
1816 * 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 * load_order. Returns the load order priority of the table. It
1822 is an integer and defaults to 0 (zero).
1823 * 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 * 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 * master_nodes. Returns the master nodes of a table.
1833 * memory. Returns the number of words allocated to the table
1835 on this node.
1836 * ram_copies. Returns the nodes where a ram_copy of the table
1838 resides according to the schema.
1839 * record_name. Returns the record name, common for all records
1841 in the table.
1842 * size. Returns the number of records inserted in the table.
1844 * snmp. Returns the SNMP struct. [] means that the table cur‐
1846 rently has no SNMP properties.
1847 * 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 * subscribers. Returns a list of local processes currently
1854 subscribing to local table events that involve this table on
1855 this node.
1856 * type. Returns the table type, which is bag, set, or
1858 ordered_set.
1859 * user_properties. Returns the user-associated table proper‐
1861 ties of the table. It is a list of the stored property
1862 records.
1863 * 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 * 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 * where_to_write. Returns a list of the nodes that currently
1876 hold an active replica of the table.
1877 * 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 transaction(Fun [[, Args], Retries]) -> {aborted, Reason} | {atomic,
1883 ResultOfFun}
1884 Executes the functional object Fun with arguments Args as a
1886 transaction.
1887 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 If all is going well, {atomic, ResultOfFun} is returned, where
1896 ResultOfFun is the value of the last expression in Fun.
1897 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 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 oid(Rec) -> {element(1, Rec), element(2, Rec)}.
1913 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 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 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 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 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 transform_table(Tab, Fun, NewAttributeList, NewRecordName) -> {aborted,
1949 R} | {atomic, ok}
1950 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 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 transform_table(Tab, Fun, NewAttributeList) -> {aborted, R} | {atomic,
1965 ok}
1966 Calls mnesia:transform_table(Tab, Fun, NewAttributeList, Rec‐
1968 Name), where RecName is mnesia:table_info(Tab, record_name).
1969 traverse_backup(Source, [SourceMod,] Target, [TargetMod,] Fun, Acc) ->
1971 {ok, LastAcc} | {error, Reason}
1972 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 * SourceMod and TargetMod are the names of the modules that
1978 actually access the backup media.
1979 * Source and Target are opaque data used exclusively by mod‐
1981 ules SourceMod and TargetMod to initialize the backup media.
1982 * Acc is an initial accumulator value.
1984 * 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 * LastAcc is the last accumulator value. This is the last
1992 NewAcc value that was returned by Fun.
1993 uninstall_fallback() -> ok | {error,Reason}
1995 Calls the function mnesia:uninstall_fallback([{scope, global}]).
1997 uninstall_fallback(Args) -> ok | {error,Reason}
1999 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 Args is a list of the following tuples:
2010 * {module, BackupMod}. For semantics, see mnesia:install_fall‐
2012 back/2.
2013 * {scope, Scope}. For semantics, see mnesia:install_fall‐
2015 back/2.
2016 * {mnesia_dir, AlternateDir}. For semantics, see mne‐
2018 sia:install_fallback/2.
2019 unsubscribe(EventCategory) -> {ok, Node} | {error, Reason}
2021 Stops sending events of type EventCategory to the caller.
2023 Node is the local node.
2025 wait_for_tables(TabList, Timeout) -> ok | {timeout, BadTabList} |
2027 {error, Reason}
2028 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 wread({Tab, Key}) -> transaction abort | RecordList
2035 Calls the function mnesia:read(Tab, Key, write).
2037 write(Record) -> transaction abort | ok
2039 Calls the function mnesia:write(Tab, Record, write), where Tab
2041 is element(1, Record).
2042 write(Tab, Record, LockKind) -> transaction abort | ok
2044 Writes record Record to table Tab.
2046 The function returns ok, or terminates if an error occurs. For
2048 example, the transaction terminates if no person table exists.
2049 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 write_lock_table(Tab) -> ok | transaction abort
2056 Calls the function mnesia:lock({table, Tab}, write).
2058
2060 Mnesia reads the following application configuration parameters:
2061 * -mnesia access_module Module. The name of the Mnesia activity
2063 access callback module. Default is mnesia.
2064 * -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 * -mnesia backup_module Module. The name of the Mnesia backup call‐
2070 back module. Default is mnesia_backup.
2071 * -mnesia debug Level. Controls the debug level of Mnesia. The possi‐
2073 ble values are as follows:
2074 none:
2076 No trace outputs. This is the default.
2077 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 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 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 false:
2099 An alias for none.
2100 true:
2102 An alias for debug.
2103 * -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 * -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 * -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 * -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 * -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 This feature is temporary and will be removed in a future release
2127 * -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 *
2133 -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 *
2141 -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 * -mnesia event_module Module. The name of the Mnesia event handler
2150 callback module. Default is mnesia_event.
2151 * -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 * -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 * -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 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 * -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 * -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 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 * -mnesia schema_location Loc. Controls where Mnesia looks for its
2200 schema. Parameter Loc can be one of the following atoms:
2201 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 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 Parameter extra_db_nodes can also be used on disc based nodes.
2216 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 First, the SASL application parameters are checked, then the command-
2226 line flags are checked, and finally, the default value is chosen.
2227
2229 application(3), dets(3), disk_log(3), ets(3), mnesia_registry(3),
2230 qlc(3)
2231Ericsson AB mnesia 4.16.1 mnesia(3)