doc/poddoc/database.pod

=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: flatfile.C,v 1.3 2007-07-21 13:23:18 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, mulist)
         {
           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 () >>.
Revision:	1.1
Committed:	Tue Aug 28 17:14:42 2007 UTC (19 years, 2 months ago) by pippijn
Branch:	MAIN
Log Message:	added new files
#	User	Rev	Content
1	pippijn	1.1	=head1 Database backends
2
3			Ermyth has a powerful modular database facility. The core merely provides an
4			interface, backend modules do the rest. Everything database-related lives
5			under the C<database> namespace.
6
7			=head2 Writing a new database backend
8
9			First, you will want to include the headers defining data structures for all
10			data you want to load/store.
11
12			#include <boost/foreach.hpp> // provides the foreach macro
13
14			#include "atheme.h"
15			#include <ermyth/database.h>
16			#include <account/chanacs.h>
17			#include <account/kline.h>
18			#include <account/metadata.h>
19			#include <account/mychan.h>
20			#include <account/mymemo.h>
21			#include <account/mynick.h>
22			#include <account/myuser.h>
23			#include <account/svsignore.h>
24
25			Every translation unit requires an rcsid:
26
27			static char const rcsid[] = "$Id: flatfile.C,v 1.3 2007-07-21 13:23:18 pippijn Exp $";
28
29			Define the handler class:
30
31			namespace database
32			{
33			struct mybackend : handler
34			{
35			mybackend ()
36			{
37			backend_loaded = true;
38			}
39
40			// backends won't be unloaded at runtime,
41			// so we need no destructor
42
43			virtual void save ();
44			virtual void load ();
45			};
46
47			void
48			mybackend::save ()
49			{
50			/**
51			* Maybe open a file, a database connection, a http
52			* connection or anything else where you want to store
53			* the data. The following is an example of a fictive
54			* storage facility. This is not part of ermyth.
55			*/
56			dbconnection conn ("http://localhost/ermythdata", 8000);
57
58			/**
59			* The following is an example of what you can do with
60			* the structures. Internal structures are described in
61			* the Datastructures developer document.
62			*/
63			foreach (myuser_t *mu, mulist)
64			{
65			printf ("Storing myuser %s\n", mu->name);
66			printf ("his/her password is %s\n", mu->pass);
67			printf ("and the email address is %s\n", mu->email);
68			conn.store ("myuser", mu->name, mu->pass, mu->email);
69			}
70
71			// Here you can do the same with other data. Storing
72			// data should not change it.
73			}
74
75			void
76			mybackend::load ()
77			{
78			// Open storage like you did in mybackend::save ()
79			dbconnection conn ("http://localhost/ermythdata", 8000);
80
81			/**
82			* Depending on what kind of storage you used, you will
83			* have to do specific things with the connection. Here is
84			* a more or less pseudo-code example:
85			*/
86			while (conn.has_more ("myuser"))
87			{
88			char muname = conn.load<char > ("myuser", "name");
89			char mupass = conn.load<char > ("myuser", "pass");
90			char mumail = conn.load<char > ("myuser", "email");
91			long muregistered = conn.load<long> ("myuser", "registered");
92
93			myuser_t *mu = myuser::create (muname, mupass, mumail, muregistered);
94			}
95			}
96			} // namespace database
97
98			The last thing we need to do is register our database backend with the
99			database factory:
100
101			#define FACREG_TYPE database::mybackend
102			#define FACREG_TYPE_NAME "mybackend"
103			#define FACREG_INTERFACE_TYPE database::handler
104			#include <ermyth/factory_reg.h>
105
106			=head2 Using the new backend
107
108			Now, after compiling the module, the backend is available to the services and
109			can be loaded using the C<backend> configuration directive:
110
111			backend "mybackend";
112
113			Usage of the database backend within ermyth is simple. Saving the current
114			state is done by invoking C<< backend->save () >> and loading is
115			C<< backend->load () >>.