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.inc">
   5 %myents;
   6 ]>
   7
   8 <appendix id="appendix">
   9   <title>Database Back-ends</title>
  10
  11     <sect1 id="postgresql">
  12       <title>PostgreSQL</title>
  13       <sect2>
  14         <title>Libraries</title>
  15         <para>The PostgreSQL back-end requires the PostgreSQL C
  16           client library (<filename>libpq.so</filename>).  The
  17           location of this library is specified via
  18           <symbol>*postgresql-so-load-path*</symbol>, which defaults
  19           to <filename>/usr/lib/libpq.so</filename>.  Additional flags
  20           to <application>ld</application> needed for linking are
  21           specified via <symbol>*postgresql-so-libraries*</symbol>,
  22           which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
  23       </sect2>
  24       <sect2>
  25         <title>Initialization</title>
  26         <para>Use
  27           <screen>
  28 (asdf:operate 'asdf:load-op 'clsql-postgresql)
  29         </screen>
  30           to load the PostgreSQL back-end.  The database type for the
  31           PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
  32       </sect2>
  33       <sect2>
  34         <title>Connection Specification</title>
  35         <sect3>
  36           <title>Syntax of connection-spec</title>
  37           <synopsis>
  38             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
  39           </synopsis>
  40         </sect3>
  41         <sect3>
  42           <title>Description of connection-spec</title>
  43           <para>
  44             For every parameter in the connection-spec,
  45             <symbol>nil</symbol> indicates that the PostgreSQL default
  46             environment variables (see PostgreSQL documentation) will
  47             be used, or if those are unset, the compiled-in defaults
  48             of the C client library are used.
  49           </para>
  50           <variablelist>
  51             <varlistentry>
  52               <term><parameter>host</parameter></term>
  53               <listitem>
  54                 <para>String representing the hostname or IP address
  55                   the PostgreSQL server resides on.  Use the empty
  56                   string to indicate a connection to localhost via
  57                   Unix-Domain sockets instead of TCP/IP.</para>
  58               </listitem>
  59             </varlistentry>
  60             <varlistentry>
  61               <term><parameter>db</parameter></term>
  62               <listitem>
  63                 <para>String representing the name of the database on
  64                   the server to connect to.</para>
  65               </listitem>
  66             </varlistentry>
  67             <varlistentry>
  68               <term><parameter>user</parameter></term>
  69               <listitem>
  70                 <para>String representing the user name to use for
  71                   authentication.</para>
  72               </listitem>
  73             </varlistentry>
  74             <varlistentry>
  75               <term><parameter>password</parameter></term>
  76               <listitem>
  77                 <para>String representing the unencrypted password to
  78                   use for authentication.</para>
  79               </listitem>
  80             </varlistentry>
  81             <varlistentry>
  82               <term><parameter>port</parameter></term>
  83               <listitem>
  84                 <para>String representing the port to use for
  85                   communication with the PostgreSQL server.</para>
  86               </listitem>
  87             </varlistentry>
  88             <varlistentry>
  89               <term><parameter>options</parameter></term>
  90               <listitem>
  91                 <para>String representing further runtime options for
  92                   the PostgreSQL server.</para>
  93               </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96               <term><parameter>tty</parameter></term>
  97               <listitem>
  98                 <para>String representing the tty or file to use for
  99                   debugging messages from the PostgreSQL server.</para>
 100               </listitem>
 101             </varlistentry>
 102           </variablelist>
 103         </sect3>
 104       </sect2>
 105     </sect1>
 106
 107     <sect1 id="postgresql-socket">
 108       <title>PostgreSQL Socket</title>
 109       <sect2>
 110         <title>Libraries</title>
 111         <para>The PostgreSQL Socket back-end needs
 112           <emphasis>no</emphasis> access to the PostgreSQL C
 113           client library, since it communicates directly with the
 114           PostgreSQL server using the published frontend/backend
 115           protocol, version 2.0.  This eases installation and makes it
 116           possible to dump CMU CL images containing CLSQL and this
 117           backend, contrary to backends which require FFI code.</para>
 118       </sect2>
 119       <sect2>
 120         <title>Initialization</title>
 121         <para>
 122           Use
 123           <screen>
 124 (asdf:operate 'asdf:load-op 'clsql-postgresql-socket)
 125         </screen>
 126           to load the PostgreSQL Socket back-end.  The database type
 127           for the PostgreSQL Socket back-end is
 128           <symbol>:postgresql-socket</symbol>.
 129         </para>
 130       </sect2>
 131       <sect2>
 132         <title>Connection Specification</title>
 133         <sect3>
 134           <title>Syntax of connection-spec</title>
 135           <synopsis>
 136             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
 137           </synopsis>
 138         </sect3>
 139         <sect3>
 140           <title>Description of connection-spec</title>
 141           <variablelist>
 142             <varlistentry>
 143               <term><parameter>host</parameter></term>
 144               <listitem>
 145                 <para>If this is a string, it represents the hostname or
 146                   IP address the PostgreSQL server resides on.  In
 147                   this case communication with the server proceeds via
 148                   a TCP connection to the given host and port.</para>
 149                 <para>
 150                   If this is a pathname, then it is assumed to name the
 151                   directory that contains the server's Unix-Domain
 152                   sockets.  The full name to the socket is then
 153                   constructed from this and the port number passed,
 154                   and communication will proceed via a connection to
 155                   this unix-domain socket.</para>
 156               </listitem>
 157             </varlistentry>
 158             <varlistentry>
 159               <term><parameter>db</parameter></term>
 160               <listitem>
 161                 <para>String representing the name of the database on
 162                   the server to connect to.</para>
 163               </listitem>
 164             </varlistentry>
 165             <varlistentry>
 166               <term><parameter>user</parameter></term>
 167               <listitem>
 168                 <para>String representing the user name to use for
 169                   authentication.</para>
 170               </listitem>
 171             </varlistentry>
 172             <varlistentry>
 173               <term><parameter>password</parameter></term>
 174               <listitem>
 175                 <para>String representing the unencrypted password to
 176                   use for authentication.  This can be the empty
 177                   string if no password is required for
 178                   authentication.</para>
 179               </listitem>
 180             </varlistentry>
 181             <varlistentry>
 182               <term><parameter>port</parameter></term>
 183               <listitem>
 184                 <para>Integer representing the port to use for
 185                   communication with the PostgreSQL server.  This
 186                   defaults to 5432.</para>
 187               </listitem>
 188             </varlistentry>
 189             <varlistentry>
 190               <term><parameter>options</parameter></term>
 191               <listitem>
 192                 <para>String representing further runtime options for
 193                   the PostgreSQL server.</para>
 194               </listitem>
 195             </varlistentry>
 196             <varlistentry>
 197               <term><parameter>tty</parameter></term>
 198               <listitem>
 199                 <para>String representing the tty or file to use for
 200                   debugging messages from the PostgreSQL server.</para>
 201               </listitem>
 202             </varlistentry>
 203           </variablelist>
 204         </sect3>
 205       </sect2>
 206     </sect1>
 207
 208   <sect1 id="mysql">
 209     <title>MySQL</title>
 210     <sect2>
 211       <title>Libraries</title>
 212       <para>The &mysql; back-end requires the &mysql; C
 213         client library (<filename>libmysqlclient.so</filename>).
 214         The location of this library is specified
 215         via <symbol>*mysql-so-load-path*</symbol>, which defaults
 216         to <filename>/usr/lib/libmysqlclient.so</filename>.
 217         Additional flags to <application>ld</application> needed for
 218         linking are specified via <symbol>*mysql-so-libraries*</symbol>,
 219         which defaults to <symbol>("-lc")</symbol>.
 220       </para>
 221     </sect2>
 222     <sect2>
 223       <title>Initialization</title>
 224       <para>
 225         Use
 226         <screen>
 227 (asdf:operate 'asdf:load-op 'clsql-mysql)
 228         </screen>
 229         to load the &mysql; back-end.  The database type for the MySQL
 230         back-end is <symbol>:mysql</symbol>.
 231       </para>
 232       </sect2>
 233       <sect2>
 234         <title>Connection Specification</title>
 235         <sect3>
 236           <title>Syntax of connection-spec</title>
 237           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 238         </sect3>
 239         <sect3>
 240           <title>Description of connection-spec</title>
 241           <variablelist>
 242             <varlistentry>
 243               <term><parameter>host</parameter></term>
 244               <listitem>
 245                 <para>String representing the hostname or IP address
 246                   the &mysql; server resides on, or <symbol>nil</symbol>
 247                   to indicate the localhost.</para>
 248               </listitem>
 249             </varlistentry>
 250             <varlistentry>
 251               <term><parameter>db</parameter></term>
 252               <listitem>
 253                 <para>String representing the name of the database on
 254                   the server to connect to.</para>
 255               </listitem>
 256             </varlistentry>
 257             <varlistentry>
 258               <term><parameter>user</parameter></term>
 259               <listitem>
 260                 <para>String representing the user name to use for
 261                   authentication, or <symbol>nil</symbol> to use the
 262                   current Unix user ID.</para>
 263               </listitem>
 264             </varlistentry>
 265             <varlistentry>
 266               <term><parameter>password</parameter></term>
 267               <listitem>
 268                 <para>String representing the unencrypted password to
 269                   use for authentication, or <symbol>nil</symbol> if
 270                   the authentication record has an empty password
 271                   field.</para>
 272               </listitem>
 273             </varlistentry>
 274           </variablelist>
 275         </sect3>
 276       </sect2>
 277     </sect1>
 278
 279     <sect1 id="odbc">
 280       <title>&odbc;</title>
 281       <sect2>
 282         <title>Libraries</title>
 283         <para>
 284           The &odbc; back-end requires access to an &odbc; driver
 285           manager as well as &odbc; drivers for the underlying
 286           database server. &clsql; has been tested with
 287           <application>unixODBC</application> ODBC Driver Manager as
 288           well as Microsoft's ODBC manager.  These driver managers
 289           have been tested with the <ulink
 290           url="http://odbc.postgresql.org">
 291           <citetitle>psqlODBC</citetitle></ulink> driver for
 292           &postgresql; and the <ulink
 293           url="http://www.mysql.com/products/connector/odbc/">
 294           <citetitle>MyODBC</citetitle></ulink> driver for &mysql;.
 295         </para>
 296       </sect2>
 297       <sect2>
 298         <title>Initialization</title>
 299         <para>
 300           Use
 301           <screen>
 302 (asdf:operate 'asdf:load-op 'clsql-odbc)
 303           </screen>
 304           to load the &odbc; back-end.  The database type for the &odbc;
 305           back-end is <symbol>:odbc</symbol>.
 306         </para>
 307       </sect2>
 308       <sect2>
 309         <title>Connection Specification</title>
 310         <sect3>
 311           <title>Syntax of connection-spec</title>
 312           <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 313         </sect3>
 314         <sect3>
 315           <title>Description of connection-spec</title>
 316           <variablelist>
 317             <varlistentry>
 318               <term><parameter>dsn</parameter></term>
 319               <listitem>
 320                 <para>String representing the ODBC data source name.</para>
 321               </listitem>
 322             </varlistentry>
 323             <varlistentry>
 324               <term><parameter>user</parameter></term>
 325               <listitem>
 326                 <para>String representing the user name to use for
 327                   authentication.</para>
 328               </listitem>
 329             </varlistentry>
 330             <varlistentry>
 331               <term><parameter>password</parameter></term>
 332               <listitem>
 333                 <para>String representing the unencrypted password to
 334                   use for authentication.</para>
 335               </listitem>
 336             </varlistentry>
 337           </variablelist>
 338         </sect3>
 339       </sect2>
 340     </sect1>
 341
 342     <sect1 id="aodbc">
 343       <title>&aodbc;</title>
 344       <sect2>
 345         <title>Libraries</title> <para>The &aodbc; back-end requires
 346         access to the &odbc; interface of &acl; named DBI. This
 347         interface is not available in the trial version of
 348         &acl;</para>
 349       </sect2>
 350       <sect2>
 351         <title>Initialization</title>
 352         <para>
 353           Use
 354           <screen>
 355 (require 'aodbc-v2)
 356 (asdf:operate 'asdf:load-op 'clsql-aodbc)
 357           </screen>
 358           to load the &aodbc; back-end.  The database type for the &aodbc;
 359           back-end is <symbol>:aodbc</symbol>.
 360         </para>
 361       </sect2>
 362       <sect2>
 363         <title>Connection Specification</title>
 364         <sect3>
 365           <title>Syntax of connection-spec</title>
 366           <synopsis>
 367             (<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)
 368           </synopsis>
 369         </sect3>
 370         <sect3>
 371           <title>Description of connection-spec</title>
 372           <variablelist>
 373             <varlistentry>
 374               <term><parameter>dsn</parameter></term>
 375               <listitem>
 376                 <para>String representing the ODBC data source name.</para>
 377               </listitem>
 378             </varlistentry>
 379             <varlistentry>
 380               <term><parameter>user</parameter></term>
 381               <listitem>
 382                 <para>String representing the user name to use for
 383                   authentication.</para>
 384               </listitem>
 385             </varlistentry>
 386             <varlistentry>
 387               <term><parameter>password</parameter></term>
 388               <listitem>
 389                 <para>String representing the unencrypted password to
 390                   use for authentication.</para>
 391               </listitem>
 392             </varlistentry>
 393           </variablelist>
 394         </sect3>
 395       </sect2>
 396     </sect1>
 397
 398     <sect1 id="sqlite">
 399       <title>&sqlite;</title>
 400       <sect2>
 401         <title>Libraries</title> <para>The &sqlite; back-end requires
 402         the &sqlite; shared library file. Its default file name is
 403         <filename>/usr/lib/libsqlite.so</filename>.</para>
 404       </sect2>
 405       <sect2>
 406         <title>Initialization</title>
 407         <para>
 408           Use
 409           <screen>
 410 (asdf:operate 'asdf:load-op 'clsql-sqlite)
 411           </screen>
 412           to load the &sqlite; back-end.  The database type for the &sqlite;
 413           back-end is <symbol>:sqlite</symbol>.
 414         </para>
 415       </sect2>
 416       <sect2>
 417         <title>Connection Specification</title>
 418         <sect3>
 419           <title>Syntax of connection-spec</title>
 420           <synopsis>(<replaceable>filename</replaceable>)</synopsis>
 421         </sect3>
 422         <sect3>
 423           <title>Description of connection-spec</title>
 424           <variablelist>
 425             <varlistentry>
 426               <term><parameter>filename</parameter></term>
 427               <listitem>
 428                 <para>String representing the filename of the &sqlite;
 429                 database file.</para>
 430               </listitem>
 431             </varlistentry>
 432           </variablelist>
 433         </sect3>
 434       </sect2>
 435     </sect1>
 436
 437   <sect1 id="oracle">
 438     <title>Oracle</title>
 439     <sect2>
 440       <title>Libraries</title>
 441       <para>The &oracle; back-end requires the &oracle; OCI client
 442       library. (<filename>libclntsh.so</filename>).  The location of
 443       this library is specified relative to the
 444       <symbol>ORACLE_HOME</symbol> value in the operating system
 445       environment. &clsql; has tested sucessfully using the client
 446       library from Oracle 9i and Oracle 10g server installations as
 447       well as Oracle's 10g Instant Client library.
 448       </para>
 449     </sect2>
 450     <sect2>
 451       <title>Initialization</title>
 452       <para>
 453         Use
 454         <screen>
 455 (asdf:operate 'asdf:load-op 'clsql-oracle)
 456         </screen>
 457         to load the &oracle; back-end.  The database type for the Oracle
 458         back-end is <symbol>:oracle</symbol>.
 459       </para>
 460       </sect2>
 461       <sect2>
 462         <title>Connection Specification</title>
 463         <sect3>
 464           <title>Syntax of connection-spec</title>
 465           <synopsis>(<replaceable>global-name</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 466         </sect3>
 467         <sect3>
 468           <title>Description of connection-spec</title>
 469           <variablelist>
 470             <varlistentry>
 471               <term><parameter>global-name</parameter></term>
 472               <listitem>
 473                 <para>String representing the global name of the Orace database.
 474                   This is looked up through the tnsnames.ora file.</para>
 475               </listitem>
 476             </varlistentry>
 477             <varlistentry>
 478               <term><parameter>user</parameter></term>
 479               <listitem>
 480                 <para>String representing the user name to use for
 481                   authentication.</para>
 482               </listitem>
 483             </varlistentry>
 484             <varlistentry>
 485               <term><parameter>password</parameter></term>
 486               <listitem>
 487                 <para>String representing the password to
 488                   use for authentication..</para>
 489               </listitem>
 490             </varlistentry>
 491           </variablelist>
 492         </sect3>
 493       </sect2>
 494     </sect1>
 495
 496   </appendix>