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">
8 <appendix id="appendix">
9 <title>Database Back-ends</title>
11 <sect1 id="postgresql">
12 <title>PostgreSQL</title>
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>
25 <title>Initialization</title>
28 (asdf:operate 'asdf:load-op 'clsql-postgresql)
30 to load the PostgreSQL back-end. The database type for the
31 PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
34 <title>Connection Specification</title>
36 <title>Syntax of connection-spec</title>
38 (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
42 <title>Description of connection-spec</title>
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.
52 <term><parameter>host</parameter></term>
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>
61 <term><parameter>db</parameter></term>
63 <para>String representing the name of the database on
64 the server to connect to.</para>
68 <term><parameter>user</parameter></term>
70 <para>String representing the user name to use for
71 authentication.</para>
75 <term><parameter>password</parameter></term>
77 <para>String representing the unencrypted password to
78 use for authentication.</para>
82 <term><parameter>port</parameter></term>
84 <para>String representing the port to use for
85 communication with the PostgreSQL server.</para>
89 <term><parameter>options</parameter></term>
91 <para>String representing further runtime options for
92 the PostgreSQL server.</para>
96 <term><parameter>tty</parameter></term>
98 <para>String representing the tty or file to use for
99 debugging messages from the PostgreSQL server.</para>
107 <sect1 id="postgresql-socket">
108 <title>PostgreSQL Socket</title>
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>
120 <title>Initialization</title>
124 (asdf:operate 'asdf:load-op 'clsql-postgresql-socket)
126 to load the PostgreSQL Socket back-end. The database type
127 for the PostgreSQL Socket back-end is
128 <symbol>:postgresql-socket</symbol>.
132 <title>Connection Specification</title>
134 <title>Syntax of connection-spec</title>
136 (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
140 <title>Description of connection-spec</title>
143 <term><parameter>host</parameter></term>
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>
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>
159 <term><parameter>db</parameter></term>
161 <para>String representing the name of the database on
162 the server to connect to.</para>
166 <term><parameter>user</parameter></term>
168 <para>String representing the user name to use for
169 authentication.</para>
173 <term><parameter>password</parameter></term>
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>
182 <term><parameter>port</parameter></term>
184 <para>Integer representing the port to use for
185 communication with the PostgreSQL server. This
186 defaults to 5432.</para>
190 <term><parameter>options</parameter></term>
192 <para>String representing further runtime options for
193 the PostgreSQL server.</para>
197 <term><parameter>tty</parameter></term>
199 <para>String representing the tty or file to use for
200 debugging messages from the PostgreSQL server.</para>
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>.
223 <title>Initialization</title>
227 (asdf:operate 'asdf:load-op 'clsql-mysql)
229 to load the &mysql; back-end. The database type for the MySQL
230 back-end is <symbol>:mysql</symbol>.
234 <title>Connection Specification</title>
236 <title>Syntax of connection-spec</title>
237 <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
240 <title>Description of connection-spec</title>
243 <term><parameter>host</parameter></term>
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>
251 <term><parameter>db</parameter></term>
253 <para>String representing the name of the database on
254 the server to connect to.</para>
258 <term><parameter>user</parameter></term>
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>
266 <term><parameter>password</parameter></term>
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
280 <title>&odbc;</title>
282 <title>Libraries</title>
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;.
298 <title>Initialization</title>
302 (asdf:operate 'asdf:load-op 'clsql-odbc)
304 to load the &odbc; back-end. The database type for the &odbc;
305 back-end is <symbol>:odbc</symbol>.
309 <title>Connection Specification</title>
311 <title>Syntax of connection-spec</title>
312 <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
315 <title>Description of connection-spec</title>
318 <term><parameter>dsn</parameter></term>
320 <para>String representing the ODBC data source name.</para>
324 <term><parameter>user</parameter></term>
326 <para>String representing the user name to use for
327 authentication.</para>
331 <term><parameter>password</parameter></term>
333 <para>String representing the unencrypted password to
334 use for authentication.</para>
343 <title>&aodbc;</title>
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
351 <title>Initialization</title>
356 (asdf:operate 'asdf:load-op 'clsql-aodbc)
358 to load the &aodbc; back-end. The database type for the &aodbc;
359 back-end is <symbol>:aodbc</symbol>.
363 <title>Connection Specification</title>
365 <title>Syntax of connection-spec</title>
367 (<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)
371 <title>Description of connection-spec</title>
374 <term><parameter>dsn</parameter></term>
376 <para>String representing the ODBC data source name.</para>
380 <term><parameter>user</parameter></term>
382 <para>String representing the user name to use for
383 authentication.</para>
387 <term><parameter>password</parameter></term>
389 <para>String representing the unencrypted password to
390 use for authentication.</para>
399 <title>&sqlite;</title>
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>
406 <title>Initialization</title>
410 (asdf:operate 'asdf:load-op 'clsql-sqlite)
412 to load the &sqlite; back-end. The database type for the &sqlite;
413 back-end is <symbol>:sqlite</symbol>.
417 <title>Connection Specification</title>
419 <title>Syntax of connection-spec</title>
420 <synopsis>(<replaceable>filename</replaceable>)</synopsis>
423 <title>Description of connection-spec</title>
426 <term><parameter>filename</parameter></term>
428 <para>String representing the filename of the &sqlite;
429 database file.</para>
438 <title>Oracle</title>
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.
451 <title>Initialization</title>
455 (asdf:operate 'asdf:load-op 'clsql-oracle)
457 to load the &oracle; back-end. The database type for the Oracle
458 back-end is <symbol>:oracle</symbol>.
462 <title>Connection Specification</title>
464 <title>Syntax of connection-spec</title>
465 <synopsis>(<replaceable>global-name</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
468 <title>Description of connection-spec</title>
471 <term><parameter>global-name</parameter></term>
473 <para>String representing the global name of the Orace database.
474 This is looked up through the tnsnames.ora file.</para>
478 <term><parameter>user</parameter></term>
480 <para>String representing the user name to use for
481 authentication.</para>
485 <term><parameter>password</parameter></term>
487 <para>String representing the password to
488 use for authentication..</para>