<refentrytitle>DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Class</emphasis> <emphasis role="bold">DATABASE</emphasis></refname>
+ <refname>DATABASE</refname>
<refpurpose>The super-type of all &clsql; databases</refpurpose>
<refclass>Class</refclass>
</refnamediv>
<refentrytitle>*CONNECT-IF-EXISTS*</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Variable</emphasis> <emphasis role="bold">*CONNECT-IF-EXISTS*</emphasis></refname>
+ <refname>*CONNECT-IF-EXISTS*</refname>
<refpurpose>Default value for the
<parameter>if-exists</parameter> parameter of <link
linkend="connect"><function>connect</function></link>.</refpurpose>
<refsect1>
<title>Value Type</title>
<para>A valid argument to the <parameter>if-exists</parameter>
- parameter of <function>connect</function>, i.e. one of
+ parameter of <function>connect</function>, that is, one of
<simplelist type="inline">
<member><symbol>:new</symbol></member>
<member><symbol>:warn-new</symbol></member>
<para>None.</para>
</refsect1>
</refentry>
+ <refentry id="db-pool-max-free-connections">
+ <refmeta>
+ <refentrytitle>*DB-POOL-MAX-FREE-CONNECTIONS*</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>*DB-POOL-MAX-FREE-CONNECTIONS*</refname>
+ <refpurpose>How many free connections should the connection pool try to keep.</refpurpose>
+ <refclass>Parameter</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Value Type</title>
+ <para>Integer</para>
+ </refsect1>
+ <refsect1>
+ <title>Initial Value</title>
+ <para>4</para>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>Threshold of free-connections in the pool before we
+ disconnect a database rather than returning it to the pool. NIL for
+ no limit. This is really a heuristic that should, on avg keep the
+ free connections about this size.</para>
+ <note>
+ <para>This is not a hard limit, the number of connections in
+ the pool may exceed this value.</para>
+ </note>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+ (setf clsql-sys:*db-pool-max-free-connections* 2)
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Affected By</title>
+ <para>None</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>
+ <note>
+ <para></para>
+ </note>
+ </refsect1>
+ </refentry>
+
<refentry id="default-database">
<refmeta>
<refentrytitle>*DEFAULT-DATABASE*</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE*</emphasis></refname>
+ <refname>*DEFAULT-DATABASE*</refname>
<refpurpose>The default database object to use.</refpurpose>
<refclass>Variable</refclass>
</refnamediv>
<refentrytitle>*DEFAULT-DATABASE-TYPE*</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE-TYPE*</emphasis></refname>
+ <refname>*DEFAULT-DATABASE-TYPE*</refname>
<refpurpose>The default database type to use</refpurpose>
<refclass>Variable</refclass>
</refnamediv>
<refentrytitle>*INITIALIZED-DATABASE-TYPES*</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Variable</emphasis> <emphasis role="bold">*INITIALIZED-DATABASE-TYPES*</emphasis></refname>
+ <refname>*INITIALIZED-DATABASE-TYPES*</refname>
<refpurpose>List of all initialized database types</refpurpose>
<refclass>Variable</refclass>
</refnamediv>
<refentrytitle>CONNECT</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECT</emphasis></refname>
+ <refname>CONNECT</refname>
<refpurpose>create a connection to a database.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
- <title>Syntax</title>
- <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> <replaceable>make-default</replaceable> => <returnvalue>database</returnvalue></synopsis>
+ <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> <replaceable>make-default</replaceable> => <returnvalue>database</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<varlistentry>
<term><parameter>connection-spec</parameter></term>
<listitem>
- <para>A vendor specific connection specification supplied
- as a list or as a string.</para>
+ <para>A SQL backend specific connection specification
+ supplied as a list or as a string.</para>
+ <para>For the MySQL backend, this list includes an
+ optional associative list of connection options. The
+ options list is parsed and supplied to the MySQL API
+ using <function>mysql_options</function> in between the
+ calls to <function>mysql_init</function>
+ and <function>mysql_real_connect</function>.</para>
</listitem>
</varlistentry>
<varlistentry>
<title>Affected by</title>
<para>
<simplelist>
- <member><symbol>*default-database-type*</symbol></member>
- <member><symbol>*connect-if-exists*</symbol></member>
+ <member>
+ <link linkend="default-database-type">
+ <symbol>*default-database-type*</symbol>
+ </link>
+ </member>
+ <member>
+ <link linkend="connect-if-exists">
+ <symbol>*connect-if-exists*</symbol>
+ </link>
+ </member>
</simplelist>
</para>
</refsect1>
<refentrytitle>CONNECTED-DATABASES</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECTED-DATABASES</emphasis></refname>
+ <refname>CONNECTED-DATABASES</refname>
<refpurpose>Return the list of active database objects.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>DATABASE-NAME</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME</emphasis></refname>
+ <refname>DATABASE-NAME</refname>
<refpurpose>Get the name of a database object</refpurpose>
<refclass>Generic Function</refclass>
</refnamediv>
<refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME-FROM-SPEC</emphasis></refname>
+ <refname>DATABASE-NAME-FROM-SPEC</refname>
<refpurpose>Return the database name string corresponding to
the given connection specification.</refpurpose>
<refclass>Generic Function</refclass>
<refentrytitle>DATABASE-TYPE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-TYPE</emphasis></refname>
+ <refname>DATABASE-TYPE</refname>
<refpurpose>Get the type of a database object.</refpurpose>
<refclass>Generic Function</refclass>
</refnamediv>
<refentrytitle>DISCONNECT</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT</emphasis></refname>
+ <refname>DISCONNECT</refname>
<refpurpose>close a database connection</refpurpose>
<refclass>Function</refclass>
</refnamediv>
</refsect1>
<refsect1>
<title>Side Effects</title>
- <para>The database connection is closed, and the database
- object is removed from the list of connected databases as
- returned by <function>connected-databases</function>.</para>
- <para>The state of the database object is changed to
- <type>closed</type>.</para>
+ <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>
+ <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><symbol>*default-database*</symbol></member>
+ <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>
<refentrytitle>DISCONNECT-POOLED</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT-POOLED</emphasis></refname>
+ <refname>DISCONNECT-POOLED</refname>
<refpurpose>closes all pooled database connections</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
- <synopsis><function>disconnect-pooled</function> => <returnvalue>t</returnvalue></synopsis>
+ <synopsis><function>disconnect-pooled</function> &optional <symbol>clear</symbol> => <returnvalue>t</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Description</title>
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>
</refsect1>
<refsect1>
<title>Side Effects</title>
- <para>Database connections will be closed and entries in the pool are removed.
- </para>
+ <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>
<refentrytitle>FIND-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">FIND-DATABASE</emphasis></refname>
+ <refname>FIND-DATABASE</refname>
<refpurpose>>Locate a database object through it's
name.</refpurpose>
<refclass>Function</refclass>
<refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">INITIALIZE-DATABASE-TYPE</emphasis></refname>
+ <refname>INITIALIZE-DATABASE-TYPE</refname>
<refpurpose>Initializes a database type</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>RECONNECT</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">RECONNECT</emphasis></refname>
+ <refname>RECONNECT</refname>
<refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>STATUS</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">STATUS</emphasis></refname>
+ <refname>STATUS</refname>
<refpurpose>Print information about connected databases.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>CREATE-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-DATABASE</emphasis></refname>
+ <refname>CREATE-DATABASE</refname>
<refpurpose>create a database</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>DESTROY-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">DESTROY-DATABASE</emphasis></refname>
+ <refname>DESTROY-DATABASE</refname>
<refpurpose>destroys a database</refpurpose>
<refclass>Function</refclass>
</refnamediv>
=>
Error: While trying to access database localhost/test2/root
using database-type POSTGRESQL:
- Error database-destory failed: dropdb: database removal failed: ERROR: database "test2" does not exist
+ Error database-destroy failed: dropdb: database removal failed: ERROR: database "test2" does not exist
has occurred.
[condition type: CLSQL-ACCESS-ERROR]
</screen>
<refentrytitle>PROBE-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">PROBE-DATABASE</emphasis></refname>
+ <refname>PROBE-DATABASE</refname>
<refpurpose>tests for existence of a database</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refentrytitle>LIST-DATABASES</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-DATABASES</emphasis></refname>
+ <refname>LIST-DATABASES</refname>
<refpurpose>List databases matching the supplied connection spec
and database type.</refpurpose>
<refclass>Function</refclass>
<refentrytitle>WITH-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DATABASE</emphasis></refname>
+ <refname>WITH-DATABASE</refname>
<refpurpose>Execute a body of code with a variable bound to a
specified database object.</refpurpose>
<refclass>Macro</refclass>
<varlistentry>
<term><parameter>db-var</parameter></term>
<listitem>
- <para>A variable to which the specified database is bound.
+ <para>A variable which is bound to the specified database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>connect-args</parameter></term>
<listitem>
- <para>Other optional arguments to <function>connect</function>.
+ <para>Other optional arguments to
+ <function>connect</function>. This macro use a value of
+ &nil; for <function>connect</function>'s
+ <replaceable>make-default</replaceable> key, This is in
+ contrast to to the connect function which has a default
+ value of &t; for <replaceable>make-default</replaceable>.
</para>
</listitem>
</varlistentry>
<refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
</refmeta>
<refnamediv>
- <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DEFAULT-DATABASE</emphasis></refname>
+ <refname>WITH-DEFAULT-DATABASE</refname>
<refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
<refclass>Macro</refclass>
</refnamediv>
projects / clsql.git / blobdiff