Design and implementation
=========================

Overview
--------

The database backend is split into multiple parts, each having a backend specific implementation

* ``common/database/Database<backend>.py`` - Implements ``common/database/DatabaseInterface.py`` which is a wrapper for access to the database, including querying. See :ref:`databaseinterface` for further details.
* ``common/database/DB<backend>.py`` - Implements ``common/database/DBProxy.py`` which is a high level interface to functionality needed to make Python objects persistent. See :ref:`dbproxy` for further details.
* ``common/database/DB<backend>Select.py`` - Implements ``common/database/DBSelect.py`` which is a high level interface to functionality search for persistent objects using a Python-like query syntax. See :ref:`dbselect` for further details.
* ...

The following example demonstrates the simplest possible method to query a default database backend, in this case Oracle

.. code-block:: python

   from common.database.Database import database

   database.connect()
   for row in database.execute_select('SELECT :1 FROM DUAL', 42):
       print(row)
   database.disconnect()



.. _databaseinterface:

DatabaseInterface
-----------------

The ``DatabaseInterface`` for a specific database backend is imported as ``Database`` by ``common/database/Database.py`` based on the contents of ``Env['database_engine']``. The ``DatabaseInterface`` implementation should also provide a ``database_api`` that refers to module that implements the Python DB\-API. The reference implementation for the interface is ``DatabaseOracle`` in ``common/database/DatabaseOracle.py``.

=============== ================== ============
database_engine DatabaseInterface  database_api
=============== ================== ============
filebased       DatabaseFilebased  None
MySQL           DatabaseMySQL      MySQLdb
oracle_9i       DatabaseOracle     cx_Oracle
oracle_10g      DatabaseOracle     cx_Oracle
postgresql      DatabasePostgreSQL `psycopg2 <https://wiki.python.org/moin/PostgreSQL>`_
sqlite          DatabaseSQLite     sqlite3
=============== ================== ============



.. _dbproxy:

DBProxy
-------

The ``DBProxy`` class has only a few high level methods that are needed to implement persistency. [#f1]_

* ``commit(self, other)`` - store a Python object and all its dependencies in a database backend.
* ``get_instance(self, cls, *args, **kwargs)`` - fetch a Pyton instance from a database backend.
* ``register_class(self, cls)`` - make a Python class known to a database backend.
* ``persists(self)`` - returns whether a Python instance is persistent.

.. [#f1] Ideally, the ``DBProxy`` class does not need a database backend specific implementation.

The ``DBProxy`` is instantiated by ``common/database/DBProxyFactory.py`` based on ``Env['database_engine']``.

=============== ==================
database_engine DBProxy
=============== ==================
filebased       DBFilebasedProxy
MySQL           DBMySQLProxy
oracle_9i       DBOracleProxy
oracle_10g      DBOracleProxy
postgresql      DBPostgreSQLProxy
sqlite          DBSQLiteProxy
=============== ==================