<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1997</year><year>2009</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>Introduction</title>
    <prepared>Claes Wikstr&ouml;m, Hans Nilsson and H&aring;kan Mattsson</prepared>
    <responsible>Bjarne D&auml;cker</responsible>
    <docno></docno>
    <approved>Bjarne D&auml;cker</approved>
    <checked>Bjarne D&auml;cker</checked>
    <date></date>
    <rev>C</rev>
    <file>Mnesia_chap1.xml</file>
  </header>
  <p>This book describes the Mnesia DataBase Management
    System (DBMS). <em>Mnesia</em> is a distributed Database Management
    System, appropriate for telecommunications applications and other
    Erlang applications which require continuous operation and soft
    real-time properties. It is one section of the Open Telecom Platform
    (OTP), which is a control system platform for building
    telecommunications applications.</p>

  <section>
    <title>About Mnesia</title>
    <p>The management of data in telecommunications system has many
      aspects whereof some, but not all, are addressed by traditional
      commercial DBMSs (Data Base Management Systems). In particular the
      very high level of fault tolerance which is required in many nonstop
      systems,  combined with requirements on the DBMS to run in the same
      address space as the application, have led us to implement a brand new
      DBMS. called Mnesia. Mnesia is implemented in, and very tightly
      connected to, the programming language Erlang and it provides the
      functionality that is necessary for the implementation of fault 
      tolerant telecommunications systems. Mnesia is a multiuser Distributed
      DBMS specially made for industrial telecommunications applications
      written in the symbolic programming language Erlang, which is also 
      the intended target language. Mnesia tries to address all of the data
      management issues required for typical telecommunications systems and
      it has a number of features that are not normally found in traditional
      databases.      <br></br>

      In telecommunications applications there are different needs 
      from the features provided by traditional DBMSs. The applications now
      implemented in the Erlang language need a mixture of a broad range
      of features, which generally are not satisfied by traditional DBMSs.
      Mnesia is designed with requirements like the following in mind:</p>
    <list type="ordered">
      <item>Fast real-time key/value lookup</item>
      <item>Complicated non real-time queries mainly for
       operation and maintenance</item>
      <item>Distributed data due to distributed 
       applications</item>
      <item>High fault tolerance</item>
      <item>Dynamic re-configuration</item>
      <item>Complex objects</item>
    </list>
    <p>What
      sets Mnesia apart from most other DBMSs is that it is designed with
      the typical data management problems of telecommunications applications
      in mind. Hence Mnesia combines many concepts found in traditional
      databases, such as transactions and queries with concepts found in data
      management systems for telecommunications applications, such as very
      fast real-time operations, configurable degree of fault tolerance (by
      means of replication) and the ability to reconfigure the system without
      stopping or suspending it. Mnesia is also interesting due to its tight
      coupling to the programming language Erlang, thus almost turning Erlang
      into a database programming language. This has many benefits, the
      foremost is that
      the impedance mismatch between data format used by the
      DBMS and data format used by the programming language, which is used
      to manipulate the data, completely disappears.      <br></br>
</p>
  </section>

  <section>
    <title>The Mnesia DataBase Management System (DBMS)</title>
    <p></p>

    <section>
      <title>Features</title>
      <p>Mnesia contains the following features which combine to produce a fault-tolerant,
        distributed database management system written in Erlang:
        </p>
      <list type="bulleted">
        <item>Database schema can be dynamically reconfigured at runtime.
        </item>
        <item>Tables can be declared to have properties such as location, 
         replication, and persistence.
        </item>
        <item>Tables can be moved or replicated to several nodes to improve 
         fault tolerance. The rest of the system can still access the tables 
         to read, write, and delete records.
        </item>
        <item>Table locations are transparent to the programmer. 
         Programs address table names and the system itself keeps track of 
         table locations.
        </item>
        <item>Database transactions can be distributed, and a large number of 
         functions can be called within one transaction.
        </item>
        <item>Several transactions can run concurrently, and their execution is 
         fully synchronized by the database management system. 
         Mnesia ensures that no two processes manipulate data simultaneously.
        </item>
        <item>Transactions can be assigned the property of being executed on 
         all nodes in the system, or on none. Transactions can also be bypassed 
         in favor of running so called "dirty operations", which reduce 
         overheads and run very fast.
        </item>
      </list>
      <p>Details of these features are described in the following sections.</p>
    </section>
    <p></p>

    <section>
      <title>Add-on Applications</title>
      <p>QLC and Mnesia Session can be used in conjunction with Mnesia to produce 
        specialized functions which enhance the  operational ability of Mnesia.  
        Both Mnesia Session and QLC have their own documentation as part
        of the OTP documentation set.  Below are the main features of Mnesia Session
        and QLC when used in conjunction with Mnesia:</p>
      <list type="bulleted">
        <item><em>QLC</em> has the ability to optimize the query
         compiler for the Mnesia Database Management System, essentially making
         the DBMS more efficient.</item>
        <item><em>QLC</em>, can be used as a database programming
         language for Mnesia. It includes a notation called "list
         comprehensions" and can be used to make complex database
         queries over a set of tables.</item>
        <item><em>Mnesia Session</em> is an interface for the Mnesia Database 
         Management System</item>
        <item><em>Mnesia Session</em> enables access to the
         Mnesia DBMS from foreign programming languages (i.e. other
         languages than Erlang).</item>
      </list>
      <p></p>

      <section>
        <title>When to Use Mnesia</title>
        <p>Use Mnesia with the following types of applications:
          </p>
        <list type="bulleted">
          <item>Applications that need to replicate data.
          </item>
          <item>Applications that perform complicated searches on data.
          </item>
          <item>Applications that need to use atomic transactions to 
           update several records simultaneously.
          </item>
          <item>Applications that  use soft real-time characteristics.
          </item>
        </list>
        <p>On the other hand, Mnesia may not be appropriate with the 
          following types of applications:
          </p>
        <list type="bulleted">
          <item>Programs that process plain text or binary data files
          </item>
          <item>Applications that merely need a look-up dictionary
           which can be stored to disc can utilize the standard
           library module <c>dets</c>, which is a disc based version
           of the module <c>ets</c>. 
          </item>
          <item>Applications which need disc logging facilities can
           utilize the module <c>disc_log</c> by preference.
          </item>
          <item>Not suitable for hard real time systems.
          </item>
        </list>
      </section>
    </section>

    <section>
      <title>Scope and Purpose</title>
      <p>This manual is included in the OTP document set. It describes
        how to build Mnesia database applications, and how to integrate
        and utilize the Mnesia database management system with
        OTP. Programming constructs are described, and numerous
        programming examples are included to illustrate the use of
        Mnesia.
        </p>
    </section>

    <section>
      <title>Prerequisites</title>
      <p>Readers of this manual are assumed to be familiar with system
        development principles and database management systems. Readers
        are also assumed to be familiar with the Erlang programming
        language.</p>
    </section>

    <section>
      <title>About This Book</title>
      <p>This book contains the following chapters:
        </p>
      <list type="bulleted">
        <item>Chapter 2, "Getting Started with Mnesia", introduces
         Mnesia with an example database. Examples are shown of how to
         start an Erlang session, specify a Mnesia database directory,
         initialize a database schema, start Mnesia, and create
         tables. Initial prototyping of record definitions is also
         discussed.
        </item>
        <item>Chapter 3, "Building a Mnesia Database", more formally
         describes the steps introduced in Chapter 2, namely the Mnesia
         functions which define a database schema, start Mnesia, and
         create the required tables.
        </item>
        <item>Chapter 4, "Transactions and other access contexts",
         describes the transactions properties which make Mnesia into a
         fault tolerant, real-time distributed database management
         system. This chapter also describes the concept of locking in
         order to ensure consistency in tables, and so called "dirty
         operations", or short cuts which bypass the transaction system
         to improve speed and reduce overheads.
        </item>
        <item>Chapter 5, "Miscellaneous Mnesia Features", describes
         features which enable the construction of more complex
         database applications. These features includes indexing,
         checkpoints, distribution and fault tolerance, disc-less
         nodes, replication manipulation, local content tables, concurrency,
         and object based programming in Mnesia.
        </item>
        <item>Chapter 6, "Mnesia System Information", describes the
         files contained in the Mnesia database directory, database
         configuration data, core and table dumps, as well as the
         important subject of backup, fall-back, and disaster recovery
         principles.
        </item>
        <item>Chapter 7, "Combining Mnesia with SNMP", is a short
         chapter which outlines  Mnesia  integrated with SNMP.
        </item>
        <item>Appendix A, "Mnesia Errors Messages", lists Mnesia error
         messages and their meanings.
        </item>
        <item>Appendix B, "The Backup Call Back Interface", is a
         program listing of the default implementation of this facility.
        </item>
        <item>Appendix C, "The Activity Access Call Back Interface",
         is a program outlining of one possible implementations of this facility.
        </item>
      </list>
    </section>
  </section>
</chapter>

