r10147: 09 Nov 2004 Kevin Rosenberg <kevin@rosenberg.net>

[clsql.git] / doc / appendix.xml

diff --git a/doc/appendix.xml b/doc/appendix.xml
index d6a50d9cf8aa5b4164e0aef5243564a5ea7899c5..a37c582a9459f1f2e012c45df0ac0f2d07a39f0f 100644 (file)
--- a/doc/appendix.xml
+++ b/doc/appendix.xml
@@ -583,6 +583,118 @@
       </sect2>
     </sect1>
 
+    <sect1 id="sqlite3">
+      <title>&sqlite3;</title>
+      <sect2>
+       <title>Libraries</title> <para>The &sqlite3; back-end requires
+       the &sqlite3; shared library file. Its default file name is
+       <filename>/usr/lib/libsqlite3.so</filename>.</para>
+      </sect2>
+      <sect2>
+       <title>Initialization</title>
+       <para>
+         Use 
+         <screen>
+(asdf:operate 'asdf:load-op 'clsql-sqlite3)
+         </screen>
+         to load the &sqlite3; back-end.  The database type for the &sqlite3;
+         back-end is <symbol>:sqlite3</symbol>.
+       </para>
+      </sect2>
+      <sect2>
+       <title>Connection Specification</title>
+       <sect3>
+         <title>Syntax of connection-spec</title>
+         <synopsis>(<replaceable>filename</replaceable> &amp;optional <replaceable>init-function</replaceable>)</synopsis>
+       </sect3>
+       <sect3>
+         <title>Description of connection-spec</title>
+         <variablelist>
+           <varlistentry>
+             <term><parameter>filename</parameter></term>
+             <listitem>
+               <para>String representing the filename of the &sqlite3;
+               database file.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><parameter>init-function</parameter></term>
+             <listitem>
+               <para>
+                A function designator.
+                <replaceable>init-function</replaceable> takes a
+                single argument of type
+                <type>sqlite3:sqlite3-db</type>, a foreign pointer to
+                the C descriptor of the newly opened database.
+                <replaceable>init-function</replaceable> is called by
+                the back-end immediately after &sqlite3;
+                <function>sqlite3_open</function> library function,
+                and can be used to perform optional database
+                initializations by calling foreign functions in the
+                &sqlite3; library.
+               </para>
+               <para>
+                An example of an initialization function which
+                defines a new collating sequence for text columns is
+                provided in
+                <filename>./examples/sqlite3/init-func/</filename>.
+               </para>
+             </listitem>
+           </varlistentry>
+         </variablelist>
+       </sect3>
+      </sect2>
+      <sect2><title>Notes</title>
+      <sect3><title>Connection</title> 
+      <itemizedlist mark='opencircle'>
+        <listitem>
+          <para>
+            Passing <parameter>filename</parameter> a value of
+            <filename>:memory:</filename> will create a database in
+            physical memory instead of using a file on disk.
+          </para>
+        </listitem>        
+        <listitem>
+          <para>
+            Some operations will be many times faster if database
+            integrity checking is disabled by setting the SYNCHRONOUS
+            flag to OFF (see the SQLITE manual for details).
+          </para>
+        </listitem>
+      </itemizedlist>
+      </sect3>
+      <sect3><title>FDDL</title> 
+      <itemizedlist mark='opencircle'>
+        <listitem>
+          <para>
+            The <symbol>:owner</symbol> keyword argument to the FDDL functions 
+            for listing and testing for database objects is ignored. 
+          </para>
+        </listitem>        
+        <listitem>
+          <para>
+            The <symbol>:column-list</symbol> keyword argument to
+            <link
+            linkend="create-view"><function>create-view</function></link>
+            is not supported by &sqlite3;. 
+          </para>
+        </listitem>
+      </itemizedlist>
+      </sect3>
+      <sect3><title>Symbolic SQL Syntax</title>
+      <itemizedlist mark='opencircle'>
+        <listitem>
+          <para>
+            &sqlite3; does not support the <function>all</function>,
+            <function>some</function>, <function>any</function> and
+            <function>exists</function> subquery operations. 
+          </para>
+        </listitem>
+      </itemizedlist>
+      </sect3>
+      </sect2>
+    </sect1>
+
   <sect1 id="oracle">
     <title>Oracle</title>
     <sect2>