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