+ <refname>DISCONNECT</refname>
+ <refpurpose>close a database connection</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>error</replaceable> => <returnvalue>result</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>error</parameter></term>
+ <listitem>
+ <para>A boolean flag indicating whether to signal an error
+ if <parameter>database</parameter> is non-&nil; but cannot
+ be found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database</parameter></term>
+ <listitem>
+ <para>The database to disconnect, which defaults to the
+ database indicated by
+ <symbol>*default-database*</symbol>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>result</parameter></term>
+ <listitem>
+ <para>A Boolean indicating whether a connection was
+ successfully disconnected.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>This function takes a <type>database</type> object as
+ returned by <function>connect</function>, and closes the
+ connection. If no matching database is found and
+ <parameter>error</parameter> and
+ <parameter>database</parameter> are both non-&nil; an error is
+ signaled, otherwise &nil; is returned. If the database is from a
+ pool it will be released to this pool.
+ </para>
+
+ <para>The status of the object passed is changed to closed
+ after the disconnection succeeds, thereby preventing further
+ use of the object as an argument to &clsql; functions, with
+ the exception of <function>database-name</function> and
+ <function>database-type</function>. If the user does pass a
+ closed database to any other &clsql; function, an error of
+ type <errortype>sql-fatal-error</errortype> is
+ signalled.</para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(disconnect :database (find-database "dent/newesim/dent"))
+=> T
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>The database object is removed from the list of connected databases as
+ returned by <link linkend="connected-databases"><function>connected-databases</function></link>.</para>
+ <para>If the database object passed is the same under
+ <function>eq</function> as the value of
+ <symbol>*default-database*</symbol>, then
+ <symbol>*default-database*</symbol> is set to the first
+ remaining database from
+ <function>connected-databases</function> or to &nil; if no
+ further active database exists.</para>
+ <refsect2>
+ <title>Non-pooled</title>
+ <para>The database connection is closed and the state of the
+ database object is changed to <type>closed</type>.</para>
+ </refsect2>
+ <refsect2>
+ <title>Pooled</title>
+ <para>Unless there are already <link linkend="db-pool-max-free-connections">
+ <symbol>*db-pool-max-free-connections*</symbol>
+ </link> free connections in the pool it is returned to the
+ pool, with the backend having an opportunity to run
+ generic cleanup on the connection first. If the max free
+ connections has already been reached then it is
+ disconnected as if it were not in the pool.
+ </para>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>
+ <simplelist>
+ <member>
+ <link linkend="default-database">
+ <symbol>*default-database*</symbol>
+ </link>
+ </member>
+ <member>
+ <link linkend="db-pool-max-free-connections">
+ <symbol>*db-pool-max-free-connections*</symbol>
+ </link>
+ </member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>If during the disconnection attempt an error is detected
+ (e.g. because of network trouble or any other cause), an error
+ of type <errortype>sql-error</errortype> might be
+ signalled.</para>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <simplelist>
+ <member><link linkend="connect"><function>connect</function></link></member>
+ <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="disconnect-pooled">
+ <refmeta>
+ <refentrytitle>DISCONNECT-POOLED</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>DISCONNECT-POOLED</refname>
+ <refpurpose>closes all pooled database connections</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>disconnect-pooled</function> &optional <symbol>clear</symbol> => <returnvalue>t</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>This function disconnects all database connections
+ that have been placed into the pool by calling <link
+ linkend="connect"><function>connect</function></link> with
+ :pool &t;.
+ </para>
+ <para>If optional argument <symbol>clear</symbol> is non-&nil;
+ then the connection-pool objects are also removed.</para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(disconnect-pool)
+=> T
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>Database connections will be closed and *all* entries in
+ the pool are removed. This is done with great prejudice and no
+ thought to thread safety or whether that connection is
+ currently in use.</para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>
+ <simplelist>
+ <member><function>disconnect</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>If during the disconnection attempt an error is
+ detected (e.g. because of network trouble or any other
+ cause), an error of type <errortype>clsql-error</errortype>
+ might be signalled.</para>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <simplelist>
+ <member><link linkend="connect"><function>connect</function></link></member>
+ <member><link linkend="disconnect"><function>disconnect</function></link></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para><function>disconnect-pooled</function> is a &clsql;
+ extension.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="find-database">
+ <refmeta>
+ <refentrytitle>FIND-DATABASE</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>FIND-DATABASE</refname>
+ <refpurpose>>Locate a database object through it's
+ name.</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>database</parameter></term>
+ <listitem>
+ <para>A database object or a string, denoting a database
+ name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>errorp</parameter></term>
+ <listitem>
+ <para>A generalized boolean. Defaults to
+ <symbol>t</symbol>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>db-type</parameter></term>
+ <listitem>
+ <para>
+ A keyword symbol denoting a known database back-end.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>result</returnvalue></term>
+ <listitem>
+ <para>Either a database object, or, if
+ <parameter>errorp</parameter> is &nil;,
+ possibly &nil;.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para><function>find-database</function> locates an active
+ database object given the specification in
+ <parameter>database</parameter>. If
+ <parameter>database</parameter> is an object of type
+ <type>database</type>, <function>find-database</function>
+ returns this. Otherwise it will search the active databases
+ as indicated by the list returned by
+ <function>connected-databases</function> for a database of
+ type <parameter>db-type</parameter> whose name (as returned by
+ <function>database-name</function> is equal as per
+ <function>string=</function> to the string passed as
+ <parameter>database</parameter>. If it succeeds, it returns
+ the first database found.</para>
+ <para>
+ If <parameter>db-type</parameter> is &nil; all databases
+ matching the string <parameter>database</parameter> are
+ considered. If no matching databases are found and
+ <parameter>errorp</parameter> is &nil; then &nil; is
+ returned. If <parameter>errorp</parameter> is &nil; and one or
+ more matching databases are found, then the most recently
+ connected database is returned as a first value and the
+ number of matching databases is returned as a second
+ value. If no, or more than one, matching databases are found
+ and <parameter>errorp</parameter> is true, an error is
+ signalled.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
+=> "dent/newesim/dent"
+(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
+=> #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
+(database-name *default-database*)
+=> "dent/newesim/dent"
+
+(database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
+=> "/template1/dent"
+(connect '(nil "template1" "dent" nil) :database-type :postgresql)
+=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
+(database-name *default-database*)
+=> "/template1/dent"
+
+(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
+=> "www.pmsf.de/template1/dent"
+
+(find-database "dent/newesim/dent")
+=> #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
+(find-database "/template1/dent")
+=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
+(find-database "www.pmsf.de/template1/dent" nil)
+=> NIL
+(find-database **)
+=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>None.</para>
+ </refsect1>
+ <refsect1>
+ <title>Affected By</title>
+ <para>
+ <simplelist>
+ <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>Will signal an error of type
+ <errortype>clsql-error</errortype> if no matching database
+ can be found, and <parameter>errorp</parameter> is true.
+ Will signal an error if the value of
+ <parameter>database</parameter> is neither an object of type
+ <type>database</type> nor a string.</para>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <simplelist>
+ <member><link
+ linkend="database-name"><function>database-name</function></link></member>
+ <member><link
+ linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
+ <member><link linkend="disconnect"><function>disconnect</function></link></member>
+ <member><link linkend="connect"><function>connect</function></link></member>
+ <member><link linkend="status"><function>status</function></link></member>
+ <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>The <parameter>db-type</parameter> keyword argument to
+ <function>find-database</function> is a &clsql;
+ extension. </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="initialize-database-type">
+ <refmeta>
+ <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>INITIALIZE-DATABASE-TYPE</refname>
+ <refpurpose>Initializes a database type</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis>
+ <function>initialize-database-type &key database-type</function> => <returnvalue>result</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>database-type</parameter></term>
+ <listitem>
+ <para>The database type to initialize, i.e. a keyword
+ symbol denoting a known database back-end. Defaults to
+ the value of
+ <symbol>*default-database-type*</symbol>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>result</returnvalue></term>
+ <listitem>
+ <para>Either &nil; if the initialization
+ attempt fails, or <symbol>t</symbol> otherwise.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>If the back-end specified by
+ <parameter>database-type</parameter> has not already been
+ initialized, as seen from
+ <symbol>*initialized-database-types*</symbol>, an attempt is
+ made to initialize the database. If this attempt succeeds,
+ or the back-end has already been initialized, the function
+ returns t, and places the keyword denoting the database type
+ onto the list stored in
+ <symbol>*initialized-database-types*</symbol>, if not
+ already present.</para>
+ <para>If initialization fails, the function returns
+ &nil;, and/or signals an error of type
+ <errortype>clsql-error</errortype>. The kind of action
+ taken depends on the back-end and the cause of the
+ problem.</para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+*initialized-database-types*
+=> NIL
+(setf *default-database-type* :mysql)
+=> :MYSQL
+(initialize-database-type)
+>> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
+>> Compiling Top-Level Form:
+>>
+=> T
+*initialized-database-types*
+=> (:MYSQL)
+(initialize-database-type)
+=> T
+*initialized-database-types*
+=> (:MYSQL)
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>The database back-end corresponding to the database type
+ specified is initialized, unless it has already been
+ initialized. This can involve any number of other side
+ effects, as determined by the back-end implementation (like
+ e.g. loading of foreign code, calling of foreign code,
+ networking operations, etc.). If initialization is
+ attempted and succeeds, the
+ <parameter>database-type</parameter> is pushed onto the list
+ stored in
+ <symbol>*initialized-database-types*</symbol>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>
+ <simplelist>
+ <member><symbol>*default-database-type*</symbol></member>
+ <member><symbol>*initialized-database-types*</symbol></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>If an error is encountered during the initialization
+ attempt, the back-end may signal errors of kind
+ <errortype>clsql-error</errortype>.</para>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <simplelist>
+ <member><link linkend="initialized-database-types"><function>*initialized-database-types*</function></link></member>
+ <member><link linkend="default-database-type"><function>*default-database-type*</function></link></member>
+ </simplelist>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="reconnect">
+ <refmeta>
+ <refentrytitle>RECONNECT</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>RECONNECT</refname>
+ <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>