doc/appendix.sgml

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