doc/appendix.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.xml">
   5 %myents;
   6 ]>
   7
   8 <appendix id="appendix">
   9   <title>Database Back-ends</title>
  10
  11   <sect1 id="mysql">
  12     <title>MySQL</title>
  13     <sect2>
  14       <title>Libraries</title>
  15       <para>The MySQL back-end needs access to the MySQL C
  16         client library (<filename>libmysqlclient.so</filename>).
  17         The location of this library is specified
  18         via <symbol>*mysql-so-load-path*</symbol>, which defaults
  19         to <filename>/usr/lib/libmysqlclient.so</filename>.
  20         Additional flags to <application>ld</application> needed for
  21         linking are specified via <symbol>*mysql-so-libraries*</symbol>,
  22         which defaults to <symbol>("-lc")</symbol>.
  23       </para>
  24     </sect2>
  25     <sect2>
  26       <title>Initialization</title>
  27       <para>Use
  28         <programlisting>(mk:load-system :clsql-mysql)</programlisting>
  29         to load the MySQL back-end.  The database type for the MySQL
  30         back-end is <symbol>:mysql</symbol>.</para>
  31       </sect2>
  32       <sect2>
  33         <title>Connection Specification</title>
  34         <sect3>
  35           <title>Syntax of connection-spec</title>
  36           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
  37         </sect3>
  38         <sect3>
  39           <title>Description of connection-spec</title>
  40           <variablelist>
  41             <varlistentry>
  42               <term><parameter>host</parameter></term>
  43               <listitem>
  44                 <para>String representing the hostname or IP address
  45                   the MySQL server resides on, or <symbol>nil</symbol>
  46                   to indicate the localhost.</para>
  47               </listitem>
  48             </varlistentry>
  49             <varlistentry>
  50               <term><parameter>db</parameter></term>
  51               <listitem>
  52                 <para>String representing the name of the database on
  53                   the server to connect to.</para>
  54               </listitem>
  55             </varlistentry>
  56             <varlistentry>
  57               <term><parameter>user</parameter></term>
  58               <listitem>
  59                 <para>String representing the user name to use for
  60                   authentication, or <symbol>nil</symbol> to use the
  61                   current Unix user ID.</para>
  62               </listitem>
  63             </varlistentry>
  64             <varlistentry>
  65               <term><parameter>password</parameter></term>
  66               <listitem>
  67                 <para>String representing the unencrypted password to
  68                   use for authentication, or <symbol>nil</symbol> if
  69                   the authentication record has an empty password
  70                   field.</para>
  71               </listitem>
  72             </varlistentry>
  73           </variablelist>
  74         </sect3>
  75       </sect2>
  76     </sect1>
  77
  78     <sect1 id="postgresql">
  79       <title>PostgreSQL</title>
  80       <sect2>
  81         <title>Libraries</title>
  82         <para>The PostgreSQL back-end needs access to the PostgreSQL C
  83           client library (<filename>libpq.so</filename>).  The
  84           location of this library is specified via
  85           <symbol>*postgresql-so-load-path*</symbol>, which defaults
  86           to <filename>/usr/lib/libpq.so</filename>.  Additional flags
  87           to <application>ld</application> needed for linking are
  88           specified via <symbol>*postgresql-so-libraries*</symbol>,
  89           which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
  90       </sect2>
  91       <sect2>
  92         <title>Initialization</title>
  93         <para>Use
  94           <programlisting>(mk:load-system :clsql-postgresql)</programlisting>
  95           to load the PostgreSQL back-end.  The database type for the
  96           PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
  97       </sect2>
  98       <sect2>
  99         <title>Connection Specification</title>
 100         <sect3>
 101           <title>Syntax of connection-spec</title>
 102           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
 103         </sect3>
 104         <sect3>
 105           <title>Description of connection-spec</title>
 106           <para>For every parameter in the connection-spec,
 107             <symbol>nil</symbol> indicates that the PostgreSQL default
 108             environment variables (see PostgreSQL documentation) will
 109             be used, or if those are unset, the compiled-in defaults
 110             of the C client library are used.</para>
 111           <variablelist>
 112             <varlistentry>
 113               <term><parameter>host</parameter></term>
 114               <listitem>
 115                 <para>String representing the hostname or IP address
 116                   the PostgreSQL server resides on.  Use the empty
 117                   string to indicate a connection to localhost via
 118                   Unix-Domain sockets instead of TCP/IP.</para>
 119               </listitem>
 120             </varlistentry>
 121             <varlistentry>
 122               <term><parameter>db</parameter></term>
 123               <listitem>
 124                 <para>String representing the name of the database on
 125                   the server to connect to.</para>
 126               </listitem>
 127             </varlistentry>
 128             <varlistentry>
 129               <term><parameter>user</parameter></term>
 130               <listitem>
 131                 <para>String representing the user name to use for
 132                   authentication.</para>
 133               </listitem>
 134             </varlistentry>
 135             <varlistentry>
 136               <term><parameter>password</parameter></term>
 137               <listitem>
 138                 <para>String representing the unencrypted password to
 139                   use for authentication.</para>
 140               </listitem>
 141             </varlistentry>
 142             <varlistentry>
 143               <term><parameter>port</parameter></term>
 144               <listitem>
 145                 <para>String representing the port to use for
 146                   communication with the PostgreSQL server.</para>
 147               </listitem>
 148             </varlistentry>
 149             <varlistentry>
 150               <term><parameter>options</parameter></term>
 151               <listitem>
 152                 <para>String representing further runtime options for
 153                   the PostgreSQL server.</para>
 154               </listitem>
 155             </varlistentry>
 156             <varlistentry>
 157               <term><parameter>tty</parameter></term>
 158               <listitem>
 159                 <para>String representing the tty or file to use for
 160                   debugging messages from the PostgreSQL server.</para>
 161               </listitem>
 162             </varlistentry>
 163           </variablelist>
 164         </sect3>
 165       </sect2>
 166     </sect1>
 167
 168     <sect1 id="postgresql-socket">
 169       <title>PostgreSQL Socket</title>
 170       <sect2>
 171         <title>Libraries</title>
 172         <para>The PostgreSQL Socket back-end needs
 173           <emphasis>no</emphasis> access to the PostgreSQL C
 174           client library, since it communicates directly with the
 175           PostgreSQL server using the published frontend/backend
 176           protocol, version 2.0.  This eases installation and makes it
 177           possible to dump CMU CL images containing CLSQL and this
 178           backend, contrary to backends which require FFI code.</para>
 179       </sect2>
 180       <sect2>
 181         <title>Initialization</title>
 182         <para>Use
 183           <programlisting>(mk:load-system :clsql-postgresql-socket)</programlisting>
 184           to load the PostgreSQL Socket back-end.  The database type for the
 185           PostgreSQL Socket back-end is
 186           <symbol>:postgresql-socket</symbol>.</para>
 187       </sect2>
 188       <sect2>
 189         <title>Connection Specification</title>
 190         <sect3>
 191           <title>Syntax of connection-spec</title>
 192           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
 193         </sect3>
 194         <sect3>
 195           <title>Description of connection-spec</title>
 196           <variablelist>
 197             <varlistentry>
 198               <term><parameter>host</parameter></term>
 199               <listitem>
 200                 <para>If this is a string, it represents the hostname or
 201                   IP address the PostgreSQL server resides on.  In
 202                   this case communication with the server proceeds via
 203                   a TCP connection to the given host and port.</para>
 204                 <para>
 205                   If this is a pathname, then it is assumed to name the
 206                   directory that contains the server's Unix-Domain
 207                   sockets.  The full name to the socket is then
 208                   constructed from this and the port number passed,
 209                   and communication will proceed via a connection to
 210                   this unix-domain socket.</para>
 211               </listitem>
 212             </varlistentry>
 213             <varlistentry>
 214               <term><parameter>db</parameter></term>
 215               <listitem>
 216                 <para>String representing the name of the database on
 217                   the server to connect to.</para>
 218               </listitem>
 219             </varlistentry>
 220             <varlistentry>
 221               <term><parameter>user</parameter></term>
 222               <listitem>
 223                 <para>String representing the user name to use for
 224                   authentication.</para>
 225               </listitem>
 226             </varlistentry>
 227             <varlistentry>
 228               <term><parameter>password</parameter></term>
 229               <listitem>
 230                 <para>String representing the unencrypted password to
 231                   use for authentication.  This can be the empty
 232                   string if no password is required for
 233                   authentication.</para>
 234               </listitem>
 235             </varlistentry>
 236             <varlistentry>
 237               <term><parameter>port</parameter></term>
 238               <listitem>
 239                 <para>Integer representing the port to use for
 240                   communication with the PostgreSQL server.  This
 241                   defaults to 5432.</para>
 242               </listitem>
 243             </varlistentry>
 244             <varlistentry>
 245               <term><parameter>options</parameter></term>
 246               <listitem>
 247                 <para>String representing further runtime options for
 248                   the PostgreSQL server.</para>
 249               </listitem>
 250             </varlistentry>
 251             <varlistentry>
 252               <term><parameter>tty</parameter></term>
 253               <listitem>
 254                 <para>String representing the tty or file to use for
 255                   debugging messages from the PostgreSQL server.</para>
 256               </listitem>
 257             </varlistentry>
 258           </variablelist>
 259         </sect3>
 260       </sect2>
 261     </sect1>
 262
 263     <sect1 id="aodbc">
 264       <title>AODBC</title>
 265       <sect2>
 266         <title>Libraries</title>
 267         <para>The AODBC back-end requires access to the ODBC interface
 268           of &acl;.</para>
 269       </sect2>
 270       <sect2>
 271         <title>Initialization</title>
 272         <para>Use
 273           <programlisting>(mk:load-system :clsql-aodbc)</programlisting>
 274           to load the MySQL back-end.  The database type for the AODBC
 275           back-end is <symbol>:aodbc</symbol>.</para>
 276       </sect2>
 277       <sect2>
 278         <title>Connection Specification</title>
 279         <sect3>
 280           <title>Syntax of connection-spec</title>
 281           <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 282         </sect3>
 283         <sect3>
 284           <title>Description of connection-spec</title>
 285           <variablelist>
 286             <varlistentry>
 287               <term><parameter>dsn</parameter></term>
 288               <listitem>
 289                 <para>String representing the ODBC data source name.</para>
 290               </listitem>
 291             </varlistentry>
 292             <varlistentry>
 293               <term><parameter>user</parameter></term>
 294               <listitem>
 295                 <para>String representing the user name to use for
 296                   authentication.</para>
 297               </listitem>
 298             </varlistentry>
 299             <varlistentry>
 300               <term><parameter>password</parameter></term>
 301               <listitem>
 302                 <para>String representing the unencrypted password to
 303                   use for authentication.</para>
 304               </listitem>
 305             </varlistentry>
 306           </variablelist>
 307         </sect3>
 308       </sect2>
 309     </sect1>
 310
 311   </appendix>