=head1 Database backends

Ermyth has a powerful modular database facility. The core merely provides an
interface, backend modules do the rest. Everything database-related lives
under the C<database> namespace.

=head2 Writing a new database backend

First, you will want to include the headers defining data structures for all
data you want to load/store.

   #include <boost/foreach.hpp> // provides the foreach macro

   #include "atheme.h"
   #include <ermyth/database.h>
   #include <account/chanacs.h>
   #include <account/kline.h>
   #include <account/metadata.h>
   #include <account/mychan.h>
   #include <account/mymemo.h>
   #include <account/mynick.h>
   #include <account/myuser.h>
   #include <account/svsignore.h>

Every translation unit requires an rcsid:

   static char const rcsid[] = "$Id: database.pod,v 1.2 2007/09/05 11:23:13 pippijn Exp $";

Define the handler class:

   namespace database
   {
     struct mybackend : handler
     {
       mybackend ()
       {
         backend_loaded = true;
       }

       // backends won't be unloaded at runtime,
       // so we need no destructor

       virtual void save ();
       virtual void load ();
     };

     void
     mybackend::save ()
     {
       /**
        * Maybe open a file, a database connection, a http
        * connection or anything else where you want to store
        * the data. The following is an example of a fictive
        * storage facility. This is not part of ermyth.
        */
       dbconnection conn ("http://localhost/ermythdata", 8000);

       /**
        * The following is an example of what you can do with
        * the structures. Internal structures are described in
        * the Datastructures developer document.
        */
       foreach (myuser_t *mu, myuser_t::map)
         {
           printf ("Storing myuser %s\n", mu->name);
           printf ("his/her password is %s\n", mu->pass);
           printf ("and the email address is %s\n", mu->email);
           conn.store ("myuser", mu->name, mu->pass, mu->email);
         }

       // Here you can do the same with other data. Storing
       // data should not change it.
     }

     void
     mybackend::load ()
     {
       // Open storage like you did in mybackend::save ()
       dbconnection conn ("http://localhost/ermythdata", 8000);

       /**
        * Depending on what kind of storage you used, you will
        * have to do specific things with the connection. Here is
        * a more or less pseudo-code example:
        */
       while (conn.has_more ("myuser"))
         {
           char *muname = conn.load<char *> ("myuser", "name");
           char *mupass = conn.load<char *> ("myuser", "pass");
           char *mumail = conn.load<char *> ("myuser", "email");
           long muregistered = conn.load<long> ("myuser", "registered");
           
           myuser_t *mu = myuser::create (muname, mupass, mumail, muregistered);
         }
     }
   } // namespace database

The last thing we need to do is register our database backend with the
database factory:

   #define FACREG_TYPE database::mybackend
   #define FACREG_TYPE_NAME "mybackend"
   #define FACREG_INTERFACE_TYPE database::handler
   #include <ermyth/factory_reg.h>

=head2 Using the new backend

Now, after compiling the module, the backend is available to the services and
can be loaded using the C<backend> configuration directive:

   backend "mybackend";

Usage of the database backend within ermyth is simple. Saving the current
state is done by invoking C<< backend->save () >> and loading is
C<< backend->load () >>.