Clever Harold Database Integration Guide
-----------------------------------------

Introduction
============

Clever Harold doesn't do databases.  Oh, sure, there's some help with
creating your model and maybe even connecting it at runtime.  But
beyond that, we absolutely refuse to guess how you get along with your
data models (or don't).  Instead of telling you how to use a database
-- and probably getting it wrong! -- the 0.1 release includes only a
few simple tools for database integration.  They're simple tools, but
they're handy.

For development and maintenance, we have an extension to the
``paster`` script for recreating your databases.  When you run it, it
will connect, create, and populate the data model(s) from the
configuration section you specify.  There's also a ``paster`` script
command to load your data modules into an interactive shell.

For applications, we have four simple database providers, each
middleware that can be used directly or customized via subclassing.

Both the script commands and the middleware work from your
configuration file.  There you specify the type of provider, the
connection parameters, and the names of your database models.

Database Middleware
===================

    Note:  the database middleware documentation is not complete.
    Refer to the `Database API Documentation`_ for detailed use.


We have four database providers, and they all share the same behavior:

- ActiveMapper_ 
- SQLAlchemy_
- SQLObject_
- DBAPI_

For each request to your application, they will:

#.  connect to the database if necessary
#.  run the next application
#.  if the application does not raise an exception, commit database
    changes and return application results
#.  if the application raises an exception, cancel (rollback) database
    changes and re-raise


ActiveMapper
++++++++++++


To use the ActiveMapperProvider, you first define your ActiveMapper
classe in code.  They'll start out like this::


   #!/usr/bin/env python
   from sqlalchemy import *
   from sqlalchemy.ext.activemapper import *

    __metadata__ = default_metadata

    class Author(ActiveMapper):
        class mapping:
            id = column(Integer, primary_key=True)
            name = column(String, unique=True, nullable=False)
            email = column(String, nullable=False)


SQLAlchemy
++++++++++

The SQLAlchemyProvider connects your SA tables and models prior to
servicing requests.  It flushes the sqlalchemy.objectstore after every
successful request.  To use it, make sure you import the
``objectstore`` object in each of your models.


SQLObject
+++++++++

Incomplete.


DBAPI
+++++


Incomplete.


Custom
++++++

The stock providers can be subclassed to provide alternate behavior,
and it is just as simple to write your own.  In both cases, just
provide the two expected methods::
    
    class SheepAircraftData:
        def connect(self, environ):
            ...

        def disconnect(self, environ, exception=None):
            ...
 
    class SheepAircraftPartsProvider(ActiveMapperProvider):
        def connect(self, environ):
            ... alternate connect behavior



Database Commands
=================

The 0.1 release also includes two commands that extend ``paster`` to
automate some of your database maintenance.  Refer to the `Command
Reference`_ for details.


Further Reading
---------------

- `Command Reference`_
- `Database API Documentation`_

.. _Command Reference: /documentation/command_reference
.. _Database API Documentation:  http://trac.cleverharold.org/wiki/DatabaseApiDocs
