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="foreignlibs">
  12     <title>How CLSQL finds and loads foreign  libraries</title>
  13     <para>
  14       For some database types CLSQL has to load external foreign
  15       libaries.  These are usually searched for in the standard
  16       locations the operating system uses but you can tell &clsql; to
  17       look into other directories as well by using the function
  18       <function>CLSQL:PUSH-LIBRARY-PATH</function> or by directly
  19       manipulating the special variable
  20       <varname>CLSQL:*FOREIGN-LIBRARY-SEARCH-PATHS*</varname>.  If,
  21       say, the shared library libpq.so needed for PostgreSQL support
  22       is located in the directory <filename>/opt/foo/</filename> on
  23       your machine you'd use
  24       <screen>
  25         (clsql:push-library-path "/opt/foo/")
  26       </screen>
  27   before loading the CLSQL-POSTGRESQL module.  (Note the trailing
  28   slash above!)
  29
  30   If you want to combine this with fully automatic loading of
  31   libraries via ASDF a technique like the following works:
  32
  33   <screen>
  34     (defmethod asdf:perform :after ((o asdf:load-op)
  35                                     (c (eql (asdf:find-system 'clsql))))
  36       (funcall (find-symbol (symbol-name '#:push-library-path)
  37                             (find-package 'clsql))
  38                #p"/opt/foo/"))
  39   </screen>
  40     </para>
  41
  42     <para>
  43       Additionally, site-specific initialization can be done using an
  44 initialization file. If the file <filename>/etc/clsql-init.lisp</filename>
  45 exists, this file will be read after the &clsql; ASDF system is loaded.
  46 This file can contain forms to set site-specific paths as well as change
  47 &clsql; default values.
  48     </para>
  49   </sect1>
  50   <sect1 id="postgresql">
  51     <title>PostgreSQL</title>
  52     <sect2>
  53       <title>Libraries</title>
  54       <para>The PostgreSQL back-end requires the PostgreSQL C
  55       client library (<filename>libpq.so</filename>).  The
  56       location of this library is specified via
  57           <symbol>*postgresql-so-load-path*</symbol>, which defaults
  58           to <filename>/usr/lib/libpq.so</filename>.  Additional flags
  59           to <application>ld</application> needed for linking are
  60           specified via <symbol>*postgresql-so-libraries*</symbol>,
  61           which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
  62       </sect2>
  63       <sect2>
  64         <title>Initialization</title>
  65         <para>Use
  66           <screen>
  67 (asdf:operate 'asdf:load-op 'clsql-postgresql)
  68         </screen>
  69           to load the PostgreSQL back-end.  The database type for the
  70           PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
  71       </sect2>
  72       <sect2>
  73         <title>Connection Specification</title>
  74         <sect3>
  75           <title>Syntax of connection-spec</title>
  76           <synopsis>
  77             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
  78           </synopsis>
  79         </sect3>
  80         <sect3>
  81           <title>Description of connection-spec</title>
  82           <para>
  83             For every parameter in the connection-spec,
  84             <symbol>nil</symbol> indicates that the PostgreSQL default
  85             environment variables (see PostgreSQL documentation) will
  86             be used, or if those are unset, the compiled-in defaults
  87             of the C client library are used.
  88           </para>
  89           <variablelist>
  90             <varlistentry>
  91               <term><parameter>host</parameter></term>
  92               <listitem>
  93                 <para>String representing the hostname or IP address
  94                   the PostgreSQL server resides on.  Use the empty
  95                   string to indicate a connection to localhost via
  96                   Unix-Domain sockets instead of TCP/IP.</para>
  97               </listitem>
  98             </varlistentry>
  99             <varlistentry>
 100               <term><parameter>db</parameter></term>
 101               <listitem>
 102                 <para>String representing the name of the database on
 103                   the server to connect to.</para>
 104               </listitem>
 105             </varlistentry>
 106             <varlistentry>
 107               <term><parameter>user</parameter></term>
 108               <listitem>
 109                 <para>String representing the user name to use for
 110                   authentication.</para>
 111               </listitem>
 112             </varlistentry>
 113             <varlistentry>
 114               <term><parameter>password</parameter></term>
 115               <listitem>
 116                 <para>String representing the unencrypted password to
 117                   use for authentication.</para>
 118               </listitem>
 119             </varlistentry>
 120             <varlistentry>
 121               <term><parameter>port</parameter></term>
 122               <listitem>
 123                 <para>String representing the port to use for
 124                   communication with the PostgreSQL server.</para>
 125               </listitem>
 126             </varlistentry>
 127             <varlistentry>
 128               <term><parameter>options</parameter></term>
 129               <listitem>
 130                 <para>String representing further runtime options for
 131                   the PostgreSQL server.</para>
 132               </listitem>
 133             </varlistentry>
 134             <varlistentry>
 135               <term><parameter>tty</parameter></term>
 136               <listitem>
 137                 <para>String representing the tty or file to use for
 138                   debugging messages from the PostgreSQL server.</para>
 139               </listitem>
 140             </varlistentry>
 141           </variablelist>
 142         </sect3>
 143       </sect2>
 144       <sect2><title>Notes</title>
 145       <para>None.</para>
 146       </sect2>
 147     </sect1>
 148
 149     <sect1 id="postgresql-socket">
 150       <title>PostgreSQL Socket</title>
 151       <sect2>
 152         <title>Libraries</title>
 153         <para>The PostgreSQL Socket back-end needs
 154           <emphasis>no</emphasis> access to the PostgreSQL C
 155           client library, since it communicates directly with the
 156           PostgreSQL server using the published frontend/backend
 157           protocol, version 2.0.  This eases installation and makes it
 158           possible to dump CMU CL images containing CLSQL and this
 159           backend, contrary to backends which require FFI code.</para>
 160       </sect2>
 161       <sect2>
 162         <title>Initialization</title>
 163         <para>
 164           Use
 165           <screen>
 166 (asdf:operate 'asdf:load-op 'clsql-postgresql-socket)
 167         </screen>
 168           to load the PostgreSQL Socket back-end.  The database type
 169           for the PostgreSQL Socket back-end is
 170           <symbol>:postgresql-socket</symbol>.
 171         </para>
 172       </sect2>
 173       <sect2>
 174         <title>Connection Specification</title>
 175         <sect3>
 176           <title>Syntax of connection-spec</title>
 177           <synopsis>
 178             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
 179           </synopsis>
 180         </sect3>
 181         <sect3>
 182           <title>Description of connection-spec</title>
 183           <variablelist>
 184             <varlistentry>
 185               <term><parameter>host</parameter></term>
 186               <listitem>
 187                 <para>If this is a string, it represents the hostname or
 188                   IP address the PostgreSQL server resides on.  In
 189                   this case communication with the server proceeds via
 190                   a TCP connection to the given host and port.</para>
 191                 <para>
 192                   If this is a pathname, then it is assumed to name the
 193                   directory that contains the server's Unix-Domain
 194                   sockets.  The full name to the socket is then
 195                   constructed from this and the port number passed,
 196                   and communication will proceed via a connection to
 197                   this unix-domain socket.</para>
 198               </listitem>
 199             </varlistentry>
 200             <varlistentry>
 201               <term><parameter>db</parameter></term>
 202               <listitem>
 203                 <para>String representing the name of the database on
 204                   the server to connect to.</para>
 205               </listitem>
 206             </varlistentry>
 207             <varlistentry>
 208               <term><parameter>user</parameter></term>
 209               <listitem>
 210                 <para>String representing the user name to use for
 211                   authentication.</para>
 212               </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215               <term><parameter>password</parameter></term>
 216               <listitem>
 217                 <para>String representing the unencrypted password to
 218                   use for authentication.  This can be the empty
 219                   string if no password is required for
 220                   authentication.</para>
 221               </listitem>
 222             </varlistentry>
 223             <varlistentry>
 224               <term><parameter>port</parameter></term>
 225               <listitem>
 226                 <para>Integer representing the port to use for
 227                   communication with the PostgreSQL server.  This
 228                   defaults to 5432.</para>
 229               </listitem>
 230             </varlistentry>
 231             <varlistentry>
 232               <term><parameter>options</parameter></term>
 233               <listitem>
 234                 <para>String representing further runtime options for
 235                   the PostgreSQL server.</para>
 236               </listitem>
 237             </varlistentry>
 238             <varlistentry>
 239               <term><parameter>tty</parameter></term>
 240               <listitem>
 241                 <para>String representing the tty or file to use for
 242                   debugging messages from the PostgreSQL server.</para>
 243               </listitem>
 244             </varlistentry>
 245           </variablelist>
 246         </sect3>
 247       </sect2>
 248       <sect2><title>Notes</title>
 249       <para>None.</para>
 250       </sect2>
 251     </sect1>
 252
 253   <sect1 id="mysql">
 254     <title>MySQL</title>
 255     <sect2>
 256       <title>Libraries</title>
 257       <para>The &mysql; back-end requires the &mysql; C
 258         client library (<filename>libmysqlclient.so</filename>).
 259         The location of this library is specified
 260         via <symbol>*mysql-so-load-path*</symbol>, which defaults
 261         to <filename>/usr/lib/libmysqlclient.so</filename>.
 262         Additional flags to <application>ld</application> needed for
 263         linking are specified via <symbol>*mysql-so-libraries*</symbol>,
 264         which defaults to <symbol>("-lc")</symbol>.
 265       </para>
 266     </sect2>
 267     <sect2>
 268       <title>Initialization</title>
 269       <para>
 270         Use
 271         <screen>
 272 (asdf:operate 'asdf:load-op 'clsql-mysql)
 273         </screen>
 274         to load the &mysql; back-end.  The database type for the MySQL
 275         back-end is <symbol>:mysql</symbol>.
 276       </para>
 277       </sect2>
 278       <sect2>
 279         <title>Connection Specification</title>
 280         <sect3>
 281           <title>Syntax of connection-spec</title>
 282           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable>)</synopsis>
 283         </sect3>
 284         <sect3>
 285           <title>Description of connection-spec</title>
 286           <variablelist>
 287             <varlistentry>
 288               <term><parameter>host</parameter></term>
 289               <listitem>
 290                 <para>String representing the hostname or IP address
 291                   the &mysql; server resides on, or <symbol>nil</symbol>
 292                   to indicate the localhost.</para>
 293               </listitem>
 294             </varlistentry>
 295             <varlistentry>
 296               <term><parameter>db</parameter></term>
 297               <listitem>
 298                 <para>String representing the name of the database on
 299                   the server to connect to.</para>
 300               </listitem>
 301             </varlistentry>
 302             <varlistentry>
 303               <term><parameter>user</parameter></term>
 304               <listitem>
 305                 <para>String representing the user name to use for
 306                   authentication, or <symbol>nil</symbol> to use the
 307                   current Unix user ID.</para>
 308               </listitem>
 309             </varlistentry>
 310             <varlistentry>
 311               <term><parameter>password</parameter></term>
 312               <listitem>
 313                 <para>String representing the unencrypted password to
 314                   use for authentication, or <symbol>nil</symbol> if
 315                   the authentication record has an empty password
 316                   field.</para>
 317               </listitem>
 318             </varlistentry>
 319             <varlistentry>
 320               <term><parameter>port</parameter></term>
 321               <listitem>
 322                 <para>String representing the port to use for
 323                   communication with the MySQL server.</para>
 324               </listitem>
 325             </varlistentry>
 326           </variablelist>
 327         </sect3>
 328       </sect2>
 329       <sect2><title>Notes</title>
 330       <sect3><title>FDDL</title>
 331       <itemizedlist mark='opencircle'>
 332         <listitem>
 333           <para>
 334             <link
 335             linkend="drop-index"><function>drop-index</function></link>
 336             requires a table to be specified with the
 337             <symbol>:on</symbol> keyword parameter.
 338           </para>
 339         </listitem>
 340         <listitem>
 341           <para>
 342             <glossterm linkend="gloss-view">views</glossterm> are not
 343             supported by &mysql;.
 344           </para>
 345         </listitem>
 346         <listitem>
 347           <para>
 348             The <symbol>:transactions</symbol> keyword argument to
 349             <link
 350             linkend="create-table"><function>create-table</function></link>
 351             controls whether or not the created table is an InnoDB
 352             table which supports transactions.
 353           </para>
 354         </listitem>
 355         <listitem>
 356           <para>
 357             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 358             for listing and testing for database objects is ignored.
 359           </para>
 360         </listitem>
 361       </itemizedlist>
 362       </sect3>
 363       <sect3><title>FDML</title>
 364       <itemizedlist mark='opencircle'>
 365         <listitem>
 366           <para>
 367             Prior to version 4.1, &mysql; does not support nested
 368             subqueries in calls to <link
 369             linkend="select"><function>select</function></link>.
 370           </para>
 371         </listitem>
 372       </itemizedlist>
 373       </sect3>
 374       <sect3><title>Symbolic SQL Syntax</title>
 375       <itemizedlist mark='opencircle'>
 376         <listitem>
 377           <para>
 378             &mysql; does not support the <function>||</function>
 379             concatenation operator. Use <function>concat</function>
 380             instead.
 381           </para>
 382         </listitem>
 383         <listitem>
 384           <para>
 385             &mysql; does not support the <function>substr</function>
 386             operator. Use <function>substring</function> instead.
 387           </para>
 388         </listitem>
 389         <listitem>
 390           <para>
 391             &mysql; does not support the
 392             <function>intersect</function> and
 393             <function>except</function> set operations.
 394           </para>
 395         </listitem>
 396         <listitem>
 397           <para>
 398             &mysql; (version 4.0 and later) does not support string
 399             table aliases unless the server is started with
 400             ANSI_QUOTES enabled.
 401           </para>
 402         </listitem>
 403       </itemizedlist>
 404       </sect3>
 405       </sect2>
 406     </sect1>
 407
 408     <sect1 id="odbc">
 409       <title>&odbc;</title>
 410       <sect2>
 411         <title>Libraries</title>
 412         <para>
 413           The &odbc; back-end requires access to an &odbc; driver
 414           manager as well as &odbc; drivers for the underlying
 415           database server. &clsql; has been tested with
 416           <application>unixODBC</application> ODBC Driver Manager as
 417           well as Microsoft's ODBC manager.  These driver managers
 418           have been tested with the <ulink
 419           url="http://odbc.postgresql.org">
 420           <citetitle>psqlODBC</citetitle></ulink> driver for
 421           &postgresql; and the <ulink
 422           url="http://www.mysql.com/products/connector/odbc/">
 423           <citetitle>MyODBC</citetitle></ulink> driver for &mysql;.
 424         </para>
 425       </sect2>
 426       <sect2>
 427         <title>Initialization</title>
 428         <para>
 429           Use
 430           <screen>
 431 (asdf:operate 'asdf:load-op 'clsql-odbc)
 432           </screen>
 433           to load the &odbc; back-end.  The database type for the &odbc;
 434           back-end is <symbol>:odbc</symbol>.
 435         </para>
 436       </sect2>
 437       <sect2>
 438         <title>Connection Specification</title>
 439         <sect3>
 440           <title>Syntax of connection-spec</title>
 441           <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 442         </sect3>
 443         <sect3>
 444           <title>Description of connection-spec</title>
 445           <variablelist>
 446             <varlistentry>
 447               <term><parameter>dsn</parameter></term>
 448               <listitem>
 449                 <para>String representing the ODBC data source name.</para>
 450               </listitem>
 451             </varlistentry>
 452             <varlistentry>
 453               <term><parameter>user</parameter></term>
 454               <listitem>
 455                 <para>String representing the user name to use for
 456                   authentication.</para>
 457               </listitem>
 458             </varlistentry>
 459             <varlistentry>
 460               <term><parameter>password</parameter></term>
 461               <listitem>
 462                 <para>String representing the unencrypted password to
 463                   use for authentication.</para>
 464               </listitem>
 465             </varlistentry>
 466           </variablelist>
 467         </sect3>
 468       </sect2>
 469       <sect2><title>Notes</title>
 470       <sect3><title>FDDL</title>
 471       <itemizedlist mark='opencircle'>
 472         <listitem>
 473           <para>
 474             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 475             for listing and testing for database objects is ignored.
 476           </para>
 477         </listitem>
 478       </itemizedlist>
 479       </sect3>
 480       </sect2>
 481     </sect1>
 482
 483     <sect1 id="aodbc">
 484       <title>&aodbc;</title>
 485       <sect2>
 486         <title>Libraries</title> <para>The &aodbc; back-end requires
 487         access to the &odbc; interface of &acl; named DBI. This
 488         interface is not available in the trial version of
 489         &acl;</para>
 490       </sect2>
 491       <sect2>
 492         <title>Initialization</title>
 493         <para>
 494           Use
 495           <screen>
 496 (require 'aodbc-v2)
 497 (asdf:operate 'asdf:load-op 'clsql-aodbc)
 498           </screen>
 499           to load the &aodbc; back-end.  The database type for the &aodbc;
 500           back-end is <symbol>:aodbc</symbol>.
 501         </para>
 502       </sect2>
 503       <sect2>
 504         <title>Connection Specification</title>
 505         <sect3>
 506           <title>Syntax of connection-spec</title>
 507           <synopsis>
 508             (<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)
 509           </synopsis>
 510         </sect3>
 511         <sect3>
 512           <title>Description of connection-spec</title>
 513           <variablelist>
 514             <varlistentry>
 515               <term><parameter>dsn</parameter></term>
 516               <listitem>
 517                 <para>String representing the ODBC data source name.</para>
 518               </listitem>
 519             </varlistentry>
 520             <varlistentry>
 521               <term><parameter>user</parameter></term>
 522               <listitem>
 523                 <para>String representing the user name to use for
 524                   authentication.</para>
 525               </listitem>
 526             </varlistentry>
 527             <varlistentry>
 528               <term><parameter>password</parameter></term>
 529               <listitem>
 530                 <para>String representing the unencrypted password to
 531                   use for authentication.</para>
 532               </listitem>
 533             </varlistentry>
 534           </variablelist>
 535         </sect3>
 536       </sect2>
 537       <sect2><title>Notes</title>
 538       <para>
 539         None.
 540       </para>
 541       </sect2>
 542     </sect1>
 543
 544     <sect1 id="sqlite">
 545       <title>&sqlite;</title>
 546       <sect2>
 547         <title>Libraries</title> <para>The &sqlite; back-end requires
 548         the &sqlite; shared library file. Its default file name is
 549         <filename>/usr/lib/libsqlite.so</filename>.</para>
 550       </sect2>
 551       <sect2>
 552         <title>Initialization</title>
 553         <para>
 554           Use
 555           <screen>
 556 (asdf:operate 'asdf:load-op 'clsql-sqlite)
 557           </screen>
 558           to load the &sqlite; back-end.  The database type for the &sqlite;
 559           back-end is <symbol>:sqlite</symbol>.
 560         </para>
 561       </sect2>
 562       <sect2>
 563         <title>Connection Specification</title>
 564         <sect3>
 565           <title>Syntax of connection-spec</title>
 566           <synopsis>(<replaceable>filename</replaceable>)</synopsis>
 567         </sect3>
 568         <sect3>
 569           <title>Description of connection-spec</title>
 570           <variablelist>
 571             <varlistentry>
 572               <term><parameter>filename</parameter></term>
 573               <listitem>
 574                 <para>String representing the filename of the &sqlite;
 575                 database file.</para>
 576               </listitem>
 577             </varlistentry>
 578           </variablelist>
 579         </sect3>
 580       </sect2>
 581       <sect2><title>Notes</title>
 582       <sect3><title>Connection</title>
 583       <itemizedlist mark='opencircle'>
 584         <listitem>
 585           <para>
 586             Passing <parameter>filename</parameter> a value of
 587             <filename>:memory:</filename> will create a database in
 588             physical memory instead of using a file on disk.
 589           </para>
 590         </listitem>
 591         <listitem>
 592           <para>
 593             Some operations will be many times faster if database
 594             integrity checking is disabled by setting the SYNCHRONOUS
 595             flag to OFF (see the SQLITE manual for details).
 596           </para>
 597         </listitem>
 598       </itemizedlist>
 599       </sect3>
 600       <sect3><title>FDDL</title>
 601       <itemizedlist mark='opencircle'>
 602         <listitem>
 603           <para>
 604             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 605             for listing and testing for database objects is ignored.
 606           </para>
 607         </listitem>
 608         <listitem>
 609           <para>
 610             The <symbol>:column-list</symbol> keyword argument to
 611             <link
 612             linkend="create-view"><function>create-view</function></link>
 613             is not supported by &sqlite;.
 614           </para>
 615         </listitem>
 616       </itemizedlist>
 617       </sect3>
 618       <sect3><title>Symbolic SQL Syntax</title>
 619       <itemizedlist mark='opencircle'>
 620         <listitem>
 621           <para>
 622             &sqlite; does not support the <function>all</function>,
 623             <function>some</function>, <function>any</function> and
 624             <function>exists</function> subquery operations.
 625           </para>
 626         </listitem>
 627       </itemizedlist>
 628       </sect3>
 629       </sect2>
 630     </sect1>
 631
 632     <sect1 id="sqlite3">
 633       <title>&sqlite3;</title>
 634       <sect2>
 635         <title>Libraries</title> <para>The &sqlite3; back-end requires
 636         the &sqlite3; shared library file. Its default file name is
 637         <filename>/usr/lib/libsqlite3.so</filename>.</para>
 638       </sect2>
 639       <sect2>
 640         <title>Initialization</title>
 641         <para>
 642           Use
 643           <screen>
 644 (asdf:operate 'asdf:load-op 'clsql-sqlite3)
 645           </screen>
 646           to load the &sqlite3; back-end.  The database type for the &sqlite3;
 647           back-end is <symbol>:sqlite3</symbol>.
 648         </para>
 649       </sect2>
 650       <sect2>
 651         <title>Connection Specification</title>
 652         <sect3>
 653           <title>Syntax of connection-spec</title>
 654           <synopsis>(<replaceable>filename</replaceable> &amp;optional <replaceable>init-function</replaceable>)</synopsis>
 655         </sect3>
 656         <sect3>
 657           <title>Description of connection-spec</title>
 658           <variablelist>
 659             <varlistentry>
 660               <term><parameter>filename</parameter></term>
 661               <listitem>
 662                 <para>String representing the filename of the &sqlite3;
 663                 database file.</para>
 664               </listitem>
 665             </varlistentry>
 666             <varlistentry>
 667               <term><parameter>init-function</parameter></term>
 668               <listitem>
 669                 <para>
 670                  A function designator.
 671                  <replaceable>init-function</replaceable> takes a
 672                  single argument of type
 673                  <type>sqlite3:sqlite3-db</type>, a foreign pointer to
 674                  the C descriptor of the newly opened database.
 675                  <replaceable>init-function</replaceable> is called by
 676                  the back-end immediately after &sqlite3;
 677                  <function>sqlite3_open</function> library function,
 678                  and can be used to perform optional database
 679                  initializations by calling foreign functions in the
 680                  &sqlite3; library.
 681                 </para>
 682                 <para>
 683                  An example of an initialization function which
 684                  defines a new collating sequence for text columns is
 685                  provided in
 686                  <filename>./examples/sqlite3/init-func/</filename>.
 687                 </para>
 688               </listitem>
 689             </varlistentry>
 690           </variablelist>
 691         </sect3>
 692       </sect2>
 693       <sect2><title>Notes</title>
 694       <sect3><title>Connection</title>
 695       <itemizedlist mark='opencircle'>
 696         <listitem>
 697           <para>
 698             Passing <parameter>filename</parameter> a value of
 699             <filename>:memory:</filename> will create a database in
 700             physical memory instead of using a file on disk.
 701           </para>
 702         </listitem>
 703         <listitem>
 704           <para>
 705             Some operations will be many times faster if database
 706             integrity checking is disabled by setting the SYNCHRONOUS
 707             flag to OFF (see the SQLITE manual for details).
 708           </para>
 709         </listitem>
 710       </itemizedlist>
 711       </sect3>
 712       <sect3><title>FDDL</title>
 713       <itemizedlist mark='opencircle'>
 714         <listitem>
 715           <para>
 716             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 717             for listing and testing for database objects is ignored.
 718           </para>
 719         </listitem>
 720         <listitem>
 721           <para>
 722             The <symbol>:column-list</symbol> keyword argument to
 723             <link
 724             linkend="create-view"><function>create-view</function></link>
 725             is not supported by &sqlite3;.
 726           </para>
 727         </listitem>
 728       </itemizedlist>
 729       </sect3>
 730       <sect3><title>Symbolic SQL Syntax</title>
 731       <itemizedlist mark='opencircle'>
 732         <listitem>
 733           <para>
 734             &sqlite3; does not support the <function>all</function>,
 735             <function>some</function>, <function>any</function> and
 736             <function>exists</function> subquery operations.
 737           </para>
 738         </listitem>
 739       </itemizedlist>
 740       </sect3>
 741       </sect2>
 742     </sect1>
 743
 744   <sect1 id="oracle">
 745     <title>Oracle</title>
 746     <sect2>
 747       <title>Libraries</title>
 748       <para>The &oracle; back-end requires the &oracle; OCI client
 749       library. (<filename>libclntsh.so</filename>).  The location of
 750       this library is specified relative to the
 751       <symbol>ORACLE_HOME</symbol> value in the operating system
 752       environment.
 753       </para>
 754     </sect2>
 755     <sect2>
 756       <title>Library Versions</title>
 757       <para>
 758         &clsql; has tested sucessfully using the client library from
 759         Oracle 9i and Oracle 10g server installations as well as
 760         Oracle's 10g Instant Client library. For Oracle 8 and earlier
 761         versions, there is vestigial support by pushing the symbol
 762         <symbol>:oci7</symbol> onto <symbol>cl:*features*</symbol>
 763         prior to loading the <filename>clsql-oracle</filename> &asdf;
 764         system.
 765         <screen>
 766           (push :oci7 cl:*features*)
 767           (asdf:operate 'asdf:load-op 'clsql-oracle)
 768         </screen>
 769       </para>
 770     </sect2>
 771     <sect2>
 772       <title>Initialization</title>
 773       <para>
 774         Use
 775         <screen>
 776 (asdf:operate 'asdf:load-op 'clsql-oracle)
 777         </screen>
 778         to load the &oracle; back-end.  The database type for the Oracle
 779         back-end is <symbol>:oracle</symbol>.
 780       </para>
 781       </sect2>
 782       <sect2>
 783         <title>Connection Specification</title>
 784         <sect3>
 785           <title>Syntax of connection-spec</title>
 786           <synopsis>(<replaceable>global-name</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 787         </sect3>
 788         <sect3>
 789           <title>Description of connection-spec</title>
 790           <variablelist>
 791             <varlistentry>
 792               <term><parameter>global-name</parameter></term>
 793               <listitem>
 794                 <para>String representing the global name of the Oracle database.
 795                   This is looked up through the tnsnames.ora file.</para>
 796               </listitem>
 797             </varlistentry>
 798             <varlistentry>
 799               <term><parameter>user</parameter></term>
 800               <listitem>
 801                 <para>String representing the user name to use for
 802                   authentication.</para>
 803               </listitem>
 804             </varlistentry>
 805             <varlistentry>
 806               <term><parameter>password</parameter></term>
 807               <listitem>
 808                 <para>String representing the password to
 809                   use for authentication..</para>
 810               </listitem>
 811             </varlistentry>
 812           </variablelist>
 813         </sect3>
 814       </sect2>
 815       <sect2><title>Notes</title>
 816       <sect3><title>Symbolic SQL Syntax</title>
 817       <itemizedlist mark='opencircle'>
 818         <listitem>
 819           <para>
 820             The <function>userenv</function> operator is &oracle; specific.
 821           </para>
 822         </listitem>
 823         <listitem>
 824           <para>
 825             &oracle; does not support the <function>except</function>
 826             operator. Use <function>minus</function> instead.
 827           </para>
 828         </listitem>
 829         <listitem>
 830           <para>
 831             &oracle; does not support the <function>all</function>,
 832             <function>some</function>, <function>any</function>
 833             subquery operations.
 834           </para>
 835         </listitem>
 836       </itemizedlist>
 837       </sect3>
 838       <sect3><title>Transactions</title>
 839       <itemizedlist mark='opencircle'>
 840         <listitem>
 841           <para>
 842             By default, &clsql; starts in transaction AUTOCOMMIT mode
 843             (see <link
 844             linkend="set-autocommit"><function>set-autocommit</function></link>).
 845             To begin a transaction in autocommit mode, <link
 846             linkend="start-transaction"><function>start-transaction</function></link>
 847             has to be called explicitly.
 848           </para>
 849         </listitem>
 850       </itemizedlist>
 851       </sect3>
 852       </sect2>
 853     </sect1>
 854
 855   </appendix>