<appendix id="appendix">
<title>Database Back-ends</title>
-
- <sect1 id="postgresql">
- <title>PostgreSQL</title>
- <sect2>
- <title>Libraries</title>
- <para>The PostgreSQL back-end requires the PostgreSQL C
- client library (<filename>libpq.so</filename>). The
- location of this library is specified via
+
+ <sect1 id="foreignlibs">
+ <title>How CLSQL finds and loads foreign libraries</title>
+ <para>
+ For some database types CLSQL has to load external foreign
+ libaries. These are usually searched for in the standard
+ locations the operating system uses but you can tell &clsql; to
+ look into other directories as well by using the function
+ <function>CLSQL:PUSH-LIBRARY-PATH</function> or by directly
+ manipulating the special variable
+ <varname>CLSQL:*FOREIGN-LIBRARY-SEARCH-PATHS*</varname>. If,
+ say, the shared library libpq.so needed for PostgreSQL support
+ is located in the directory <filename>/opt/foo/</filename> on
+ your machine you'd use
+ <screen>
+ (clsql:push-library-path "/opt/foo/")
+ </screen>
+ before loading the CLSQL-POSTGRESQL module. (Note the trailing
+ slash above!)
+
+ If you want to combine this with fully automatic loading of
+ libraries via ASDF a technique like the following works:
+
+ <screen>
+ (defmethod asdf:perform :after ((o asdf:load-op)
+ (c (eql (asdf:find-system 'clsql))))
+ (funcall (find-symbol (symbol-name '#:push-library-path)
+ (find-package 'clsql))
+ #p"/opt/foo/"))
+ </screen>
+ </para>
+
+ <para>
+ Additionally, site-specific initialization can be done using an
+initialization file. If the file <filename>/etc/clsql-init.lisp</filename>
+exists, this file will be read after the &clsql; ASDF system is loaded.
+This file can contain forms to set site-specific paths as well as change
+&clsql; default values.
+ </para>
+ </sect1>
+ <sect1 id="postgresql">
+ <title>PostgreSQL</title>
+ <sect2>
+ <title>Libraries</title>
+ <para>The PostgreSQL back-end requires the PostgreSQL C
+ client library (<filename>libpq.so</filename>). The
+ location of this library is specified via
<symbol>*postgresql-so-load-path*</symbol>, which defaults
to <filename>/usr/lib/libpq.so</filename>. Additional flags
to <application>ld</application> needed for linking are
<title>Connection Specification</title>
<sect3>
<title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+ <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable>)</synopsis>
</sect3>
<sect3>
<title>Description of connection-spec</title>
field.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><parameter>port</parameter></term>
+ <listitem>
+ <para>String representing the port to use for
+ communication with the MySQL server.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect3>
</sect2>
<title>Connection Specification</title>
<sect3>
<title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+ <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &key <replaceable>connection-string</replaceable>)</synopsis>
</sect3>
<sect3>
<title>Description of connection-spec</title>
use for authentication.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><parameter>connection-string</parameter></term>
+ <listitem>
+ <para>Raw connection string passed to the underlying
+ ODBC driver. Allows bypassing creating a DSN on the
+ server.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect3>
</sect2>
</itemizedlist>
</sect3>
</sect2>
+ <sect2><title>Connect Examples</title>
+ <screen>
+
+;; assumes a "mssql" DSN is configured on the lisp host, specifying database server
+;; and database name.
+> (clsql:connect '("mssql" "database-user" "database-password")
+ :database-type :odbc)
+=> #<CLSQL-ODBC:ODBC-DATABASE mssql/database-user OPEN {100756D123}>
+
+;; no DSN on the lisp host, specify connection information via :connection-string
+> (clsql:connect '("friendly-server-name" "friendly-username" ""
+ :connection-string "DRIVER={FreeTDS};SERVER=mssql-server;DATABASE=database-name;UID=database-user;PWD=database-password;PORT=1433;TDS_Version=8.0;APP=clsql")
+ :database-type :odbc)
+=> #<CLSQL-ODBC:ODBC-DATABASE friendly-server-name/friendly-username OPEN {100756D123}></screen>
+ <para>
+ The <symbol>friendly-server-name</symbol>
+ and <symbol>friendly-username</symbol> are only used when
+ printing the connection object to a stream.
+ </para>
+ </sect2>
</sect1>
<sect1 id="aodbc">
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
- <para>String representing the filename of the &sqlite;
- database file.</para>
+ <para>String or pathname representing the filename of
+ the &sqlite; database file.</para>
</listitem>
</varlistentry>
</variablelist>
projects / clsql.git / blobdiff