Update of /project/elephant/cvsroot/elephant/doc In directory clnet:/tmp/cvs-serv21396

Modified Files: user-guide.texinfo Log Message: Added CLSQL section.

--- /project/elephant/cvsroot/elephant/doc/user-guide.texinfo 2007/04/25 02:27:57 1.17 +++ /project/elephant/cvsroot/elephant/doc/user-guide.texinfo 2007/04/26 03:10:13 1.18 @@ -1308,7 +1308,40 @@ @comment node-name, next, previous, up @section CLSQL Data Store

- +Elephant uses Kevin Rosenberg's excellent @uref{http://clsql.b9.com, CLSQL} + CLSQL lisp binding to relational databases +(it does not use the ORM functionality offered by that package.) +CLSQL interfaces to many databases (Postgres, MySQL, Oracle, +ODBC, SQLite3, Microsoft SQL Server (via ODBC)). Right now, Elephant has +been tested with Postgress and SQLite3. Probably getting it to work with +one of the others will take a small amount of debugging; in principle there +is no reason it won't work out of the box. We invite users to try +other database, and will quickly incorporate patches needed to make them +work. + +Because CLSQL is very generic, the CLSQL interface does not offer any +special feature as discussed in the previous section @ref{Berkeley DB Data Store}. + +@subsection Basic CLSQL Implementation + +The CLSQL uses base64 encoding to store binary data as text directly. This +has the advantage that it works with all databases, which tend to differ +widely in their treatment of Binary Large Objects (BLOBs.) It imposes some +obvious overhead. + +The CLSQL implementation is structurally exactly the same as the BDB implementation. +A single table is created to hold all (key,value) pairs. An index on the key column +provides efficient key lookup. No additional indexing offered by the underlying +databases is used. This has the advantage that the API is exactly the same as the +BDB api, and all of the functional indexes, cursors, and secondary indexes work exactly +the same way. It does not exploit the performance that a database-specific solution +would offer (see @ref{Postmodern Data Store} for an example of such a system. + +Our basic strategy is to leave the CLSQL interface as simple as possible, in order to +work with as many databases as possible. When there is enough motivation to support +a backend that is specific to one database (and therefore probably faster), such an +interface can be placed into the ``contrib'' directory and migrated into the main +code base as time allows the complete integration with the test suite.

@node Postmodern Data Store @comment node-name, next, previous, up @@ -1317,6 +1350,9 @@ The postmodern data store is not yet integrated. It should be documented for the forthcoming release 0.9.1 or 0.9.2.

+This backend will presumably be much faster, when used against PostGres, than the +generic CLSQL store. + @node Native Lisp Data Store @comment node-name, next, previous, up @section Native Lisp Data Store