1 Mnesia Release Notes
This document describes the changes made to the Mnesia system from version to version. The intention of this document is to list all incompatibilities as well as all enhancements and bugfixes for every release of Mnesia. Each release of Mnesia thus constitutes one section in this document. The title of each section is the version number of Mnesia.
1.1 Mnesia 3.9.4
1.1.1 Improvements and new features
transform_table
now allows only meta-data transforms.
Own Id: OTP-3878
Aux Id: Seq 5057
1.1.2 Fixed Bugs and malfunctions
mnesia:table_info(Tab, type)
performance on R7B has been improved.
Own Id: OTP-3837
- Documentation referred to the non exiting function mnesia:delete_table/2.
Own Id: OTP-3778
Aux Id: Seq 5005
mnesia:all_keys/1
failed when using fragmented tables and keys of list types.
Own Id: OTP-3779
Aux Id: Seq 5006
- Fixed a bug in
mnesia:fold[lr]
functions. Records with lists as the Key field failed to show up in fold functions if they where written in the same transaction.
Own Id: OTP-3893
1.1.3 Incompatibilities
1.1.4 Known bugs and problems
1.2 Mnesia 3.9.3
1.2.1 Improvements and new features
transform_table
now supports indexes, but the dirty_index_* operations may exit when the index is rebuilt. The memory usage has been improved forset
andordered_set
tables.
Own Id: OTP-3762, OTP-3584
Aux Id: Seq 4573
- New iteration functions has been added i.e.
foldl/3 foldr/3 foldl/4 foldr/4
, together withdirty_last/1
anddirty_prev/2
forordered_set
tables.
Own Id: OTP-3761
1.2.2 Fixed Bugs and malfunctions
- A timing issue during startup has been fixed, in the worst case records written on one node fails to show up on some nodes.
1.2.3 Incompatibilities
1.2.4 Known bugs and problems
1.3 Mnesia 3.9.2
1.3.1 Improvements and new features
- Access to non-local tables avoids disc_only_replicas is possible.
1.3.2 Fixed Bugs and malfunctions
- Sometimes
dirty_read
fails during brutal kill of replicated node, this is a synchronization problem. Mnesia now behaves better but can still fail in worst case, use transactions if this behavior is not acceptable.
Own Id: OTP-3585.
Aux Id: Seq 4574
- A delete followed by a write in a transaction failed to show up in
bag
tables.
- Removed a possibility for mnesia to hang on every node if mnesia crashed on one node during startup.
- Removed a deadlock possibility when using table locks.
1.3.3 Incompatibilities
1.3.4 Known bugs and problems
1.4 Mnesia 3.9.1
1.4.1 Improvements and new features
1.4.2 Fixed Bugs and malfunctions
- Mnesia could crash during startup on ram nodes, due to a race condition.
Own Id: OTP-3557.
Aux Id: Seq 4512
1.4.3 Incompatibilities
1.4.4 Known bugs and problems
1.5 Mnesia 3.9
1.5.1 Improvements and new features
- A new configuration parameter
fallback_error_function
is introduced to let the user handle the case when mnesia have a fallback installed and and another mnesia goes down. The default behavior is as it always been to kill it self to avoid inconsistencies. The user can now start Erlang with-mnesia fallback_error_function '{UserMod, UserFunc}'
.
Own Id: OTP-3539, OTP-3057
Aux Id: Seq 4476, Seq 1590, Seq 3809
1.5.2 Fixed Bugs and malfunctions
- In earlier releases when mnesia reported
inconsistent_database
the only way to make it stop was to restart mnesia from a backup. To allow the usage ofmaster_nodes
settings, mnesia now checks if master_nodes (on the schema table) is set before reporting the inconsistency event. If set the event will not be reported.
Own Id: OTP-3551
Aux Id: Seq 4491
- If a logfile is very corrupted and disk_log fails to recognize the file as a log_file, mnesia fails to handle the case properly.
Own Id: OTP-3545
Aux Id: Seq 4492
- Mnesia table copy mechanism was not stable if the Erlang distribution went down and instantly up.
Own Id: OTP-3544
Aux Id: Seq 4493
1.5.3 Incompatibilities
- The major version number change implies that mnesia-3.9 and later will not be able to talk with other mnesia nodes which are running mnesia-3.7.*.
1.5.4 Known bugs and problems
1.6 Mnesia 3.8.6
1.6.1 Improvements and new features
1.6.2 Fixed Bugs and malfunctions
- Mnesia could crash when sending a table to another node.
Own Id: OTP-3517.
1.6.3 Incompatibilities
1.6.4 Known bugs and problems
1.7 Mnesia 3.8.5
1.7.1 Improvements and new features
1.7.2 Fixed Bugs and malfunctions
mnesia:[dirty]all_keys
didn't work with ordered_set tables.
Own Id: OTP-3467.
Aux Id: Seq 4338
1.7.3 Incompatibilities
1.7.4 Known bugs and problems
1.8 Mnesia 3.8.4
1.8.1 Improvements and new features
1.8.2 Fixed Bugs and malfunctions
mnesia:[dirty][index]_match_object
didn't work in the latest release, with index and wild_cards.
Own Id: OTP-3450.
Aux Id: Seq 4312
1.8.3 Incompatibilities
1.8.4 Known bugs and problems
1.9 Mnesia 3.8.3
1.9.1 Improvements and new features
- Subscriptions have been extended with a new more detailed event. The detailed variant is activated with
mnesia:subscribe({table, Tab, detailed}).
and the events look like {Operation, Table, Value, OldValues, Tid}.
Own Id: OTP-3356
Aux Id: Seq 4066
1.9.2 Fixed Bugs and malfunctions
- Delete objects on snmp tables, didn't work in the mnesia-3.8 releases.
Own Id: OTP-3436
Aux Id: Seq 4289
mnesia:[dirty]index_match_object
didn't work if the key was bound or the table resided on another node.
Own Id: OTP-3399
Aux Id: Seq 4229
- A couple of locking bugs has been fixed. A deadlock could occur if more than two processes were involved and one process wanted a table lock and the other wanted read and write lock and a third process held the lock.
mnesia:read(Tab, Key, write)
could if the table was deleted during the operation return a list of nodes.
- An internal deadlock in mnesia was removed. It happened during the startup when mnesia tried to connect to another node. This has only occurred when we started several mnesia nodes on the same Free-BSD machine.
mnesia:dump_to_textfile
andmnesia:load_textfile
didn't work with record_names.
1.9.3 Incompatibilities
1.9.4 Known bugs and problems
- There is issue with dangling module pointers that makes it impossible to upgrade code on the fly for the module mnesia_monitor in all earlier mnesia releases, this has now been fixed so it should not be an issue in the coming releases.
1.10 Mnesia 3.8.2
1.10.1 Improvements and new features
- Introduced
mnesia:transform_table/4
in order to make it possible to handle new record types in code upgrades.
1.10.2 Fixed Bugs and malfunctions
- Mnesia on one node can fail to load a table if master_nodes is set to another node, and the other node loads the table from a third node. Force load on the first may hang forever.
Own Id: OTP-3358.
1.10.3 Incompatibilities
1.10.4 Known bugs and problems
1.11 Mnesia 3.8.1
1.11.1 Improvements and new features
1.11.2 Fixed Bugs and malfunctions
- When using
mnesia:match_object
with partially unbound key (e.g. Key = {bar, {'_', foo}}), mnesia failed to detect that the key where unbound which could result in hanging transactions.
Own Id: OTP-3342.
Aux Id: Seq 4064.
1.11.3 Incompatibilities
1.11.4 Known bugs and problems
1.12 Mnesia 3.8
1.12.1 Improvements and new features
- Some new backup features has been introduced. The
Args
argument to the functions:mnesia:backup(Opaque,Args)
andmnesia:backup_checkpoint(Name,Opaque,Args)
has now been extended to also allow a list of options as a complement to the oldMod
atom.
- Incremental backup, enables backup of recent updates of the database, avoiding a full backup. The
{incremental,PrevName}
option specifies the name of a previously activated checkpoint, which hopefully already has been backed up. All updates that has been performed between the activation of thePrevName
checkpoint and theName
checkpoint will be included in the backup.
- Decentralized backup, enables backup of local tables, avoiding transfer of records to a central backup coordinator node. The
{scope,local}
option will cause themnesia:backup_checkpoint(Name,Opaque,Args)
function to simply ignore tables on remote nodes. Thescope
argument defaults toglobal
.
- Selective backup, enables backup of a subset of the tables included in the checkpoint, avoiding creation of huge backup files. The
{tables,TabList}
option will cause the backup functions to simply ignore all other tables than the ones included in theTabList
.
- In order to select a customized
mnesia_backup
callback module, the option{module,Mod}
is used.
- The
ram_overrides_dump
option tomnesia:activate_checkpoint
has been extended to also allow an explicit list of tables which should have theram_overrides_dump
semantics.
- It is now possible to remove a mnesia node,
mnesia:del_table_copy(schema, Node)
now completly removes the reference to the nodeNode
when the node is down. All tables which only reside on that node will be removed.
See also incompatibilities.
- Connection to other mnesia nodes can be done with
mnesia:change_config(extra_db_nodes, NodeList)
, after mnesia is started. It can be called from a node which uses disc schema to connect to new and empty ram nodes. Or it can be called from the new ram node to connect to an already existing mnesia cluster.
- The type
ordered_set
is now supported forram_copies
anddisc_copies
tables if it is supported by the Erlang runtime system, i.e. OTP R5 or later.
1.12.2 Fixed Bugs and malfunctions
mnesia:create_schema/1
created a temporary file on the current directory. This turned out to be not so splendid, especially if no write access was granted to the current directory. Now the temporary file is created on the Mnesia directory.
mnesia:restore/2
did not work if someone had subscribed to a table involved in the restore.
Own Id: OTP-3183.
Aux Id: Seq 3633.
mnesia:transform_table/3
has been made more efficient, it still uses alot memory due to the fact that all records has to be logged to disk as a single transaction.
own Id: OTP-3246.
Aux Id: Seq 3840
- A flaw in the locking mechanism caused a big overhead for lock acquisition when a lot of locks where held by the same transaction, this has now been fixed.
- The snmp hooks have been changed to use snmp_index, this should make it faster and have a smaller memory footprint for snmp tables in OTP R5 and later.
1.12.3 Incompatibilities
Mnesia
cannot be upgraded on the fly, it must be restarted with the new code, due to protocol changes.
It should be sufficient to restart onemnesia
node at the time. New functionality will not work until all nodes have been upgraded.
- In mnesia-3.7.2 the following recovery mechansim where introduced.
Mnesia generated a core dump and intentionally stopped if the log files were corrupted and contained the wrong records. Now Mnesia will generate an error event and continue if possible. This behaviour may lead to inconsistent data but Mnesia will be alive.
The statement above is only valid if configuration parameterauto_repair
is set totrue
(default). Ifauto_repair
is set tofalse
mnesia will generate a fatal event and terminate.
mnesia:del_table_copy(schema, Node)
will only work if and only if mnesia on the nodeNode
is NOT running. Beforemnesia:del_table_copy(schema, Node)
would only work if the node was running. This behavior made it impossible to remove a mnesia node when the hardware was malfunctioning.
1.12.4 Known bugs and problems
1.13 Mnesia 3.7.2
1.13.1 Improvements and new features
- Mnesia generated a core dump and intentionally stopped if the log files were corrupted and contained the wrong records. Now Mnesia will generate an error event and continue if possible. This behaviour may lead to inconsistent data but Mnesia will be alive.
Own Id: OTP-3269.
Aux Id: seq 3938.
1.13.2 Fixed Bugs and malfunctions
1.13.3 Incompatibilities
1.13.4 Known bugs and problems
1.14 Mnesia 3.7.1
1.14.1 Improvements and new features
1.14.2 Fixed Bugs and malfunctions
- Fixed a problem with table loading. Mnesia terminated if the receiving node died in a certain state.
mnesia:add_table_copy/3
did not work forlocal_content
-tables.
1.14.3 Incompatibilities
1.14.4 Known bugs and problems
1.15 Mnesia 3.7
1.15.1 Improvements and new features
mnesia:dirty_all_keys/1
has been optimized.
Own Id: OTP-2914.
Aux Id: seq 1389.
- Various optimizations has been performed, such as schema transactions.
Own Id: OTP-2804
- A concept of table fragmentation has been introduced in order to cope with very large tables. The idea is to split a table into several more manageable fragments. Each fragment is implemented as a first class Mnesia table and may be replicated, have indecies etc. as any other table.
The functionsmnesia:create_table/2
,mnesia:delete_table/1
andmnesia:table_info/2
has been extended to cope with fragmented tables.
The fragmentation properties of a table can be changed with the new functionmnesia:change_table_frag/2
.
See the Users Guide for more information.
Own Id: OTP-1748, OTP-2789.
1.15.2 Fixed Bugs and malfunctions
- Mnesia's internal process architecture has partly been redesigned in order to avoid some rare deadlock situations during startup.
Own Id: OTP-2495, OTP-2767, OTP-2421.
Aux Id: seq 4, seq 1138.
- The algorithm for copying of tables between nodes has been improved, in order to better cope with dirty updates during the copy operation.
1.15.3 Incompatibilities
Mnesia must be restarted on all nodes in order to cope with the following changes:
- The internal process architecture has been changed.
- The message protocol between nodes has been changed.
- The schema representation has been changed.
1.15.4 Known bugs and problems
The new concept of fragmented tables must be described in the
Users Guide
andReference Manual
.1.16 Mnesia 3.6
1.16.1 Improvements and new features
- The internal
OLD_DIR
directory is no more, since it was almost like a persistent memory leak.
- The fallback concept has been improved. Installation and uninstallation of fallbacks are now more predictable.
The installation is performed only on the nodes with disc resident schema. The operation will fail if the local node is not one of the disc resident nodes. Which nodes that are disc resident or not, is determined from the schema info in the backup.
The uninstallation is performed only on the nodes with disc resident schema. Which nodes that are disc resident or not, is determined from the schema info in the local fallback. The operation will fail if there is no local fallback installed.
It is now possible to install and uninstalllocal
fallbacks. By default, the installation (and uninstallation) scope of a fallback isglobal
. But if{scope, local}
is given as argument, the operation will only affect the local node. The effect of invoking the install (or uninstall) operation manually on each node with disc resident schema is the same as one single invokation with global scope.
Normally local installation and uninstallation is targeted towards the local Mnesia directory (see the-mnesia dir
configuration parameter). But if{mnesia_dir, AlternateDir}
is given as argument, the operation will be performed on the alternate directory regardless of the Mnesia directory configuration parameter setting. After installation of a fallback on an alternate Mnesia directory that directory is fully prepared for usage as an active Mnesia directory. This is a somewhat dangerous feature which must be used with care. By unintentional mixing of directories you may easily end up with a inconsistent database, if the same backup is installed on more than one directory.
Please, read more aboutmnesia:install_fallback/1,2
andmnesia:uninstall_fallback/0,1
in the reference manual.
1.16.2 Fixed Bugs and malfunctions
1.16.3 Incompatibilities
1.16.4 Known bugs and problems
1.17 Mnesia 3.5.4
1.17.1 Improvements and new features
1.17.2 Fixed Bugs and malfunctions
- This bug is an old one, but in this release the file descriptors are handled better. Notes copied from 3.1.1.
At startup, when Mnesia recreated the database from a fallback, lots of files was simultaneously opened. For large (or rather medium) size databases this caused the Erlang runtime system to encounter its hard-coded limit of 256 open ports. Mnesia no longer consumes as many open files during startup in order to avoid the system limit. The error message looked like:** FATAL ** mnesia_tm crashed: {"Cannot start from fallback", {'EXIT', {badarg, {os,ask_driver, [open_port, [{spawn,os__drv__},[]]]}}}}
1.17.3 Incompatibilities
1.17.4 Known bugs and problems
1.18 Mnesia 3.5.3
1.18.1 Improvements and new features
1.18.2 Fixed Bugs and malfunctions
- Meta table information got inconsistent when a table was copied from a node which crashed during the table transfer. This bug could lead to that the table was never loaded.
Own Id: OTP-2852.
1.18.3 Incompatibilities
1.18.4 Known bugs and problems
1.19 Mnesia 3.5.2
1.19.1 Improvements and new features
1.19.2 Fixed Bugs and malfunctions
- Dumping an ets table into a dets table caused unexpected memory consumption when the dets table resided in the ram_file'r.
1.19.3 Incompatibilities
1.19.4 Known bugs and problems
1.20 Mnesia 3.5.1
1.20.1 Improvements and new features
1.20.2 Fixed Bugs and malfunctions
- Records was sometimes skipped when iterating over a backup with the default backup module
mnesia_backup
. The error affected mnesia:restore/2,mnesia:install_fallback/1
andmnesia:traverse_backup/4,6
.
Own Id: OTP-2819.
Aux Id: seq 1261.
1.20.3 Incompatibilities
1.20.4 Known bugs and problems
1.21 Mnesia 3.5
1.21.1 Improvements and new features
1.21.2 Fixed Bugs and malfunctions
- Copying of tables between nodes has been improved. Dirty updates performed while the table is copied could sometimes be lost.
Own Id: OTP-2817.
Aux Id: seq 1258.
- The outcome (abort/commit) of heavy weight transactions was some time lost after node crashes. A new log format has been introduced and the processing of decisions in the log has been improved.
- Minor bug fixed regarding iteration of checkpoints with
disc_only_copies
-tables. It could cause inconsistent backups and inconsistent replicas if the internal hash tables grew or shrank during the iteration.
- Transient schema information about indecies was not cleaned up after
mnesia:del_table_copy/3
. This coused miscellaneous index related errors in successive operations.
- Recovery of
mnesia:create_table/2
during startup crashed on nodes without any replica.
1.21.3 Incompatibilities
1.21.4 Known bugs and problems
1.22 Mnesia 3.4.1
1.22.1 Improvements and new features
- The documentation has been enhanced.
1.22.2 Fixed Bugs and malfunctions
- A bug that caused
mnesia:wread/1
to hang infinitely has been fixed. It was a unique situation when the transaction, which invokedmnesia:wread/1
, was waiting for a write lock and a remote transaction was holding a sticky_write lock on the same record. If the remote node crashed in that situation and the remote node holding the sticky_write lock was one of the first nodes in thewhere_to_write
list of nodes, it could causemnesia:wread/1
to never return, instead of simply re-running the transaction.
- Application processes of Mnesia were neither unlinked after invocation of
mnesia:unsubscribe/1
nor shutdown. This caused spurious exit signals to be sent to the subscribing processes, when Mnesia was terminated. Subscribers ofsystem
events never receive a {mnesia_down, node()} event if a local node is stopped normally. These bugs has been fixed now.
- Some minor bugs regarding the
record_name
feature (that was introduced in 3.4) has been fixed.
1.22.3 Incompatibilities
1.22.4 Known bugs and problems
1.23 Mnesia 3.4
1.23.1 Improvements and new features
1.23.1.1 Record name may differ from table name
From this release onwards, the record name of records stored in Mnesia may differ from the name of the table that they are stored in. In order to use this new feature the table property
{record_name, Name}
has been introduced. If this property is omitted when the table is created, the table name will be used as record name. For example, if two tables are created like this:TabDef = [{record_name, subscriber}] mnesia:create_table(my_subscriber, TabDef) mnesia:create_table(your_subscriber, TabDef)it would be possible to store subscriber records in both of them:
mnesia:write(my_subscriber, #subscriber{}, sticky_write) mnesia:write(your_subscriber, #subscriber{}, write)In order to enable usage of this new support for
record_name
new functions have been added to the Mnesia API:mnesia:dirty_write(Tab, Record) mnesia:dirty_delete(Tab, Key) mnesia:dirty_delete_object(Tab, Record) mnesia:dirty_update_counter(Tab, Key, Incr) mnesia:dirty_read(Tab, Key) mnesia:dirty_match_object(Tab, Pattern) mnesia:dirty_index_match_object(Tab, Pattern, Attr) mnesia:write(Tab, Record, LockKind) mnesia:delete(Tab, Key, LockKind) mnesia:delete_object(Tab, Record, LockKind) mnesia:read(Tab, Key, LockKind) mnesia:match_object(Tab, Pattern, LockKind) mnesia:all_keys(Tab) mnesia:index_match_object(Tab, Pattern, Attr, LockKind) mnesia:index_read(Tab, SecondaryKey, Attr) LockKind ::= read | write | sticky_write | ...The old corresponding functions still exists, but are merely a syntactic sugar for the new ones:
mnesia:dirty_write(Record) -> Tab = element(1, Record), mnesia:dirty_write(Tab, Record). mnesia:dirty_delete({Tab, Key}) -> mnesia:dirty_delete(Tab, Key). mnesia:dirty_delete_object(Record) -> Tab = element(1, Record), mnesia:dirty_delete_object(Tab, Record) mnesia:dirty_update_counter({Tab, Key}, Incr) -> mnesia:dirty_update_counter(Tab, Key, Incr). mnesia:dirty_read({Tab, Key}) -> Tab = element(1, Record), mnesia:dirty_read(Tab, Key). mnesia:dirty_match_object(Pattern) -> Tab = element(1, Pattern), mnesia:dirty_match_object(Tab, Pattern). mnesia:dirty_index_match_object(Pattern, Attr) Tab = element(1, Pattern), mnesia:dirty_index_match_object(Tab, Pattern, Attr). mnesia:write(Record) -> Tab = element(1, Record), mnesia:write(Tab, Record, write). mnesia:s_write(Record) -> Tab = element(1, Record), mnesia:write(Tab, Record, sticky_write). mnesia:delete({Tab, Key}) -> mnesia:delete(Tab, Key, write). mnesia:s_delete({Tab, Key}) -> mnesia:delete(Tab, Key, sticky_write). mnesia:delete_object(Record) -> Tab = element(1, Record), mnesia:delete_object(Tab, Record, write). mnesia:s_delete_object(Record) -> Tab = element(1, Record), mnesia:delete_object(Tab, Record. sticky_write). mnesia:read({Tab, Key}) -> mnesia:read(Tab, Key, read). mnesia:wread({Tab, Key}) -> mnesia:read(Tab, Key, write). mnesia:match_object(Pattern) -> Tab = element(1, Pattern), mnesia:match_object(Tab, Pattern, read). mnesia:index_match_object(Pattern, Attr) -> Tab = element(1, Pattern), mnesia:index_match_object(Tab, Pattern, Attr, read).The earlier function semantics remain unchanged.
Use the function
mnesia:table_info(Tab, record_name)
to determine the record name of a table.If the name of all tables equals the record name that the table hosts everything is backward compatible. But if the new record_name feature is used this may affect old existing applications:
- Functions that provide read access to Mnesia tables may now return records with names that differ from the table name. Make sure your code is able to handle this.
- The backup format is slightly different and this may affect users of the
mnesia:traverse_backup/4,6
functions. When iterating over a backup, the record name is always equal to the table name regardless of the record_name setting. Make sure your code is able to handle this.
- The format of table subscription event is slightly different and this may affect users of the
mnesia:subscribe/1
function and user installedevent_module
's. When a process receives table events, the record name is always equal to the table name regardless of therecord_name
setting.
1.23.1.2 New function mnesia:lock/2
A new locking function has been introduced:
mnesia:lock(LockItem, LockKind) LockItem ::= {table, Tab} | {global, Item, Nodes} | ... LockKind ::= read | write | ...The old table locking functions still exists, but are now merely a syntactic sugar for the new functions:
mnesia:read_lock_table(Tab) -> mnesia:lock({table, Tab}, read). mnesia:write_lock_table(Tab) mnesia:lock({table, Tab}, write).1.23.1.3 New function mnesia:activity/2,3,4
In the Mnesia API there are some functions whose semantics depends of the execution context:
mnesia:lock(LockItem, LockKind) mnesia:write(Tab, Rec, LockKind) mnesia:delete(Tab, Key, LockKind) mnesia:delete_object(Tab, Rec, LockKind) mnesia:read(Tab, Key, LockKind) mnesia:match_object(Tab, Pat, LockKind) mnesia:all_keys(Tab) mnesia:index_match_object(Tab, Pat, Attr, LockKind) mnesia:index_read(Tab, SecondaryKey, Attr) mnesia:table_info(Tab, InfoItem)if these functions are executed within a
mnesia:transaction/1,2,3
, locks are acquired, atomic commit is ensured etc. If the same functions are executed within the context ofmnesia:async_dirty/1,2
,mnesia:sync_dirty/1,2
ormnesia:ets/1,2
their semantics are different. Although this is not entirely new, new functions have been introduced:mnesia:activity(ActivityKind, Fun) mnesia:activity(ActivityKind, Fun, Args) mnesia:activity(ActivityKind, Fun, Module) mnesia:activity(ActivityKind, Fun, Args, Module) ActivityKind ::= transaction | {transaction, Retries} | async_dirty | sync_dirty | etsDepending on the
ActivityKind
argument, the evaluation context will be the same as with the functions:
mnesia:transaction
,
mnesia:async_dirty
,
mnesia:sync_dirty
and
mnesia:ets
respectively. TheModule
argument provides the name of a callback module that will implement themnesia_access
behavior. It must export the functions:lock(ActivityId, Opaque, LockItem, LockKind) write(ActivityId, Opaque, Tab, Rec, LockKind) delete(ActivityId, Opaque, Tab, Key, LockKind) delete_object(ActivityId, Opaque, Tab, Rec), LockKind read(ActivityId, Opaque, Tab, Key, LockKind) match_object(ActivityId, Opaque, Tab, Pat, LockKind) all_keys(ActivityId, Opaque, Tab, LockKind) index_match_object(ActivityId, Opaque, Tab, Pat, Attr, LockKind) index_read(ActivityId, Opaque, Tab, SecondaryKey, Attr, LockKind) table_info(ActivityId, Opaque, Tab, InfoItem) ActivityId ::= A record which represents the identity of the enclosing Mnesia activity. The first field (obtained with element(1, ActivityId) contains an atom which may be interpreted as the type of the activity: 'ets', 'async_dirty', 'sync_dirty' or 'tid'. 'tid' means that the activity is a transaction. Opaque ::= An opaque data structure which is internal to Mnesia.
mnesia
andmnesia_frag
are examples of callback modules. By default themnesia
module is used as callback module for accesses within "Mnesia activities".
For example invoke the functionmnesia:read(Tab, Key, LockKind)
, and the correspondingModule:read(ActivityId, Opaque, Tab, Key, LockKind)
will be invoked to perform the job (or it will pass it on tomnesia:read(ActivityId, Opaque, Tab, Key, LockKind)
).A customized callback module may be used for several purposes, such as providing triggers, integrity constraints, run time statistics, or virtual tables. The callback module does not have to access real Mnesia tables, it is a free agent provided the callback interface is fulfilled.
The context sensitive function
mnesia:table_info/2
may be used to provide virtual information about a table. This function enables the user to performMnemosyne
queries within an activity context with a customized callback module. By providing table indices information and otherMnemosyne
requirements,Mnemosyne
can be used as an efficient generic query language for access of virtual tables.Please, read the "mnesia_access callback behavior" in Appendix C for a code example from the
mnesia_frag
module.1.23.1.4 New configuration parameter access_module
The new configuration parameter
access_module
has been added. It defaults to the atommnesia
, but may be set to any module that fulfills the callback interface withmnesia_access
behavior.The
mnesia:activity
functions will use theaccess_module
as a callback module if it not is explicitly overridden by theModule
argument.Use
mnesia:system_info(access_module)
to determine the actualaccess_module
setting.1.23.2 Fixed Bugs and malfunctions
- A bug regarding master nodes has been fixed. If all nodes only have a remote master nodes set for a table, the intended behavior is that no node should take the initiative to load the table. This now works as intended.
1.23.3 Incompatibilities
None as long as all tables only host records with the same name as the table name. Please, read the chapter
Improvements and new features
about the potential inconsistencies.1.23.4 Known bugs and problems
1.24 Mnesia 3.3
1.24.1 Improvements and new features
1.24.2 Fixed Bugs and malfunctions
mnesia:change_table_copy/3
on schema from disc_copies to ram_copies did not work on non Solaris platforms.
Own Id: OTP-2364.
- Indices of disc_only_tables did not work.
Own Id: OTP-2363.
- Shutdown of Mnesia took 30 seconds due to an internal deadlock in the application_controller. This problem is now circumvented by Mnesia.
Own Id: OTP-2664.
mnesia:set_master_nodes/1,2
may now be invoked off-line, i.e. even if Mnesia happens to be stopped.
Own Id: OTP-2425.
1.24.3 Incompatibilities
1.24.4 Known bugs and problems
No new problems or bugs. See previous release notes.
1.25 Mnesia 3.2
1.25.1 Improvements and new features
- The function
mnesia:restore/2
has eventually been implemented. The documentation of the function has been adopted to the semantics of the actual implementation. Please, read the documentation about the details.
Own Id: OTP-1560
Own Id: OTP-1736
Own Id: OTP-1824
1.25.2 Fixed Bugs and malfunctions
- Mnesia crashed if a replica was removed with
mnesia:delete_table_copy/2
before the load of the table was completed on the actual node.
Own Id: OTP-2519.
Aux Id: seq 893.
- Long table names was truncated in the printout from
mnesia:info/0
.
Own Id: OTP-2529.
Aux Id: seq 895.
1.25.3 Incompatibilities
1.25.4 Known bugs and problems
No new problems or bugs. See previous release notes.
1.26 Mnesia 3.1.1
This release is a minor release and the release notes describes the difference between version 3.1.1 and version 3.1 of Mnesia.
1.26.1 Improvements and new features
1.26.2 Fixed Bugs and malfunctions
- At startup, when Mnesia recreated the database from a fallback, lots of files was simultaneously opened. For large (or rather medium) size databases this caused the Erlang runtime system to encounter its hard-coded limit of 256 open ports. Mnesia no longer consumes as many open files during startup in order to avoid the system limit. The error message looked like:
** FATAL ** mnesia_tm crashed: {"Cannot start from fallback", {'EXIT', {badarg, {os,ask_driver, [open_port, [{spawn,os__drv__},[]]]}}}}
Own Id: OTP-2534.
Aux Id: seq 907.
1.26.3 Incompatibilities
1.26.4 Known bugs and problems
No new problems or bugs. See previous release notes.
1.27 Mnesia 3.1
1.27.1 Improvements and new features
- A new configuration parameter
ignore_fallback_at_startup
has been added. It defaults tofalse
, but if it is set totrue
it causes Mnesia to ignore the potential fallback that may have been installed withmnesia:install_fallback/2
. The new configuration parameter enables Mnesia to start with the old database even if a fallback is present.
Own Id: OTP-2530.
Aux Id: seq 903.
Aux Id: HA86394.
- Previously, Mnesia terminated itself on all nodes if a fallback was installed and Mnesia on another node was terminated. It is now possible to bypass this behavior.
When Mnesia's event handler receives a{mnesia_down, Node}
event it will check if there is any fallback active and then possibly terminate the local Mnesia system. If the user changes the configuration parameterevent_module
to an own module, the new module may simply omit to terminate Mnesia.
Own Id: OTP-2530.
Aux Id: seq 903.
Aux Id: HA86394.
1.27.2 Fixed Bugs and malfunctions
- When Mnesia encountered a fatal error, Mnesia would terminate itself on all nodes. Now Mnesia will only terminate itself on the local node as intended.
1.27.3 Incompatibilities
1.27.4 Known bugs and problems
No new problems or bugs. See previous release notes.
1.28 Mnesia 3.0
This release is a major release and the release notes describes the difference between version 3.0 and version 2.3. 3.0 is classified as major release due to the issues described in the chapter about incompatibilities described below.
1.28.1 Improvements and new features
- Mnesia's internal storage format on disc has been made more future safe.
- A new attribute in the
schema
table has been added. Calleduser_properties
, it enables applications to store its own meta data about a table together with the Meta data that is built into Mnesia. Theuser_properties
can either be set when the table is created, by stating a{user_properties,PropList}
tuple in theCreateList
given tomnesia:create_table(Tab,CreateList)
or later withmnesia:write_table_property(Tab,Prop)
.
The user propertyProp
must be a record (a tagged tuple). Subsequent calls towrite_table_property/2
with the same tag will overwrite the old setting. The property record may have any number of fields.
The user property can be read withmnesia:read_table_property(Tab,PropName)
. It returns the user property record or exits with{no_exists, {Tab,PropName}}
.
The user property can be deleted withmnesia:delete_table_property(Tab,PropertyName)
.
All user defined properties for a table can be obtained withmnesia:table_info(Tab,user_properties)
. It returns a list of the stored property records.
- All table properties that are normally obtained singularly with
mnesia:table_info(Tab,Prop)
, can be read with one single call tomnesia:table_info(Tab,all)
. It returns a list of{PropName,PropVal}
tuples.
- All system properties that are normally obtained with
mnesia:system_info(Prop)
singularly, can be read with one single call tomnesia:system_info(all)
. It returns a list of{PropName,PropVal}
tuples. If Mnesia is not running, only a subset of the properties will be returned.
- The module
mnesia_registry
has been added. It contains functions which support the customized creation of backing storage tables for registries inerl_interface
.
1.28.2 Fixed Bugs and malfunctions
No serious bugs or malfunctions.
1.28.3 Incompatibilities
Mnesia 3.0 is primary developed for OTP R4, but is still backward compatible with the OTP R3 platform.
The internal database format on disc has been made more future safe. It has also been altered in order to cope with the newly introduced features. The special upgrade procedure is as follows:
- First of all, a full backup must be performed with the old Mnesia system.
- Then the backup must be installed as fallback, preferably by the new version of Mnesia.
- At last the new version of Mnesia may be started.
Mnemosyne has been made into an own separate application. The new application is called
mnemosyne
. Please, read its release notes. This application split implies a few incompatibilities:
- The compiler directive:
-include_lib("mnesia/include/mnemosyne.hrl").that was mandatory in all Erlang modules that contains embeddedMnemosyne
queries has been replaced with:
-include_lib("mnemosyne/include/mnemosyne.hrl").During an interim period, both compiler directives will be supported. But in a future release the backward compatibility directive will be removed.
- At the startup of Mnesia, the Mnemosyne statistics process
mnemosyne_catalog
has automatically been started by Mnesia. This is not the case anymore. Themnemosyne
application must be started separately after the start of themnesia
application.
However, a temporary configuration parameterembedded_mnemosyne
has been added to allow the automatic start of Mnemosyne. By defaultembedded_mnemosyne
is set tofalse
, but if it is set totrue
Mnesia will start Mnemosyne as a supervised part of the Mnesia application as it did in previous releases.
1.28.4 Known bugs and problems
None of these are newly introduced.
- Indices of disc_only_tables does not work.
Own Id: OTP-2363.
- Changing the storage type of the schema from disc_copies to ram_copies does not work on Windows systems.
Own Id: OTP-2364.
- Mnesia will not detect if two nodes are sharing the same Mnesia directory. When two nodes are using the same Mnesia directory the result is totally unpredictable.
- mnesia:restore/1 is not implemented.
Own Id: OTP-1736.