[elephant-cvs] CVS elephant/doc

[rread]

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}.
+
+ at 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