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 <reference id="ref-connect">
9 <title>Connection and Initialisation</title>
12 This section describes the &clsql; interface for initialising
13 database interfaces of different types, creating and destroying
14 databases and connecting and disconnecting from databases.
18 <!-- Connection and Initialisation -->
20 <refentry id="database">
22 <refentrytitle>DATABASE</refentrytitle>
25 <refname><emphasis>Class</emphasis> <emphasis role="bold">DATABASE</emphasis></refname>
26 <refpurpose>The super-type of all &clsql; databases</refpurpose>
27 <refclass>Class</refclass>
30 <title>Class Precedence List</title>
32 <simplelist type="inline">
33 <member><type>database</type></member>
34 <member><type>standard-object</type></member>
35 <member><type>t</type></member>
40 <title>Description</title> <para>This class is the superclass of
41 all &clsql; databases. The different database back-ends derive
42 subclasses of this class to implement their databases. No
43 instances of this class are ever created by &clsql;.</para>
47 <title class="contenttitle">Class details</title>
48 <programlisting>(defclass DATABASE ()(...))</programlisting>
51 <title class="contenttitle">Slots</title>
54 <property>slot COMMAND-RECORDING-STREAM is of type T</property>
55 <property>slot CONN-POOL is of type T</property>
56 <property>slot NAME is of type T</property>
57 <property>slot RECORD-CACHES is of type T</property>
58 <property>slot RESULT-RECORDING-STREAM is of type T</property>
59 <property>slot STATE is of type T</property>
60 <property>slot TRANSACTION is of type T</property>
61 <property>slot TRANSACTION-LEVEL is of type T</property>
62 <property>slot VIEW-CLASSES is of type T</property>
69 <refentry id="connect-if-exists">
71 <refentrytitle>*CONNECT-IF-EXISTS*</refentrytitle>
74 <refname><emphasis>Variable</emphasis> <emphasis role="bold">*CONNECT-IF-EXISTS*</emphasis></refname>
75 <refpurpose>Default value for the
76 <parameter>if-exists</parameter> parameter of <link
77 linkend="connect"><function>connect</function></link>.</refpurpose>
78 <refclass>Variable</refclass>
81 <title>Value Type</title>
82 <para>A valid argument to the <parameter>if-exists</parameter>
83 parameter of <function>connect</function>, i.e. one of
84 <simplelist type="inline">
85 <member><symbol>:new</symbol></member>
86 <member><symbol>:warn-new</symbol></member>
87 <member><symbol>:error</symbol></member>
88 <member><symbol>:warn-old</symbol></member>
89 <member><symbol>:old</symbol></member>
94 <title>Initial Value</title>
95 <para><symbol>:error</symbol></para>
98 <title>Description</title>
99 <para>The value of this variable is used in calls to
100 <function>connect</function> as the default
101 value of the <parameter>if-exists</parameter>
103 linkend="connect"><function>connect</function></link> for
104 the semantics of the valid values for this variable.</para>
107 <title>Examples</title>
111 <title>Affected By</title>
115 <title>See Also</title>
119 linkend="connect"><function>connect</function></link></member>
129 <refentry id="default-database">
131 <refentrytitle>*DEFAULT-DATABASE*</refentrytitle>
134 <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE*</emphasis></refname>
135 <refpurpose>The default database object to use.</refpurpose>
136 <refclass>Variable</refclass>
139 <title>Value Type</title>
140 <para>Any object of type <type>database</type>, or &nil; to
141 indicate no default database.</para>
144 <title>Initial Value</title>
148 <title>Description</title>
149 <para>Any function or macro in &clsql; that operates on a
150 database uses the value of this variable as the default value
151 for it's <parameter>database</parameter> parameter.</para>
152 <para>The value of this parameter is changed by calls to
153 <function>connect</function>, which sets
154 <symbol>*default-database*</symbol> to the database object
155 it returns. It is also changed by calls to
156 <function>disconnect</function>, when the database object
157 being disconnected is the same as the value of
158 <symbol>*default-database*</symbol>. In this case
159 <function>disconnect</function> sets
160 <symbol>*default-database*</symbol> to the first database
161 that remains in the list of active databases as returned by
162 <function>connected-databases</function>, or
163 &nil; if no further active databases
165 <para>The user may change <symbol>*default-database*</symbol>
166 at any time to a valid value of his choice.</para>
168 <para>If the value of <symbol>*default-database*</symbol> is
169 &nil;, then all calls to &clsql; functions on
170 databases must provide a suitable
171 <parameter>database</parameter> parameter, or an error will be
176 <title>Examples</title>
178 (connected-databases)
180 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
181 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
182 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
183 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
184 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
185 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
187 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
191 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
195 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
200 (connected-databases)
205 <title>Affected By</title>
207 <member><link linkend="connect"><function>connect</function></link></member>
208 <member><link linkend="disconnect"><function>disconnect</function></link></member>
212 <title>See Also</title>
215 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
222 <para>This variable is intended to facilitate working with
223 &clsql; in an interactive
224 fashion at the top-level loop, and because of this,
225 <function>connect</function> and
226 <function>disconnect</function> provide some fairly
227 complex behaviour to keep
228 <symbol>*default-database*</symbol> set to useful values.
229 Programmatic use of &clsql;
230 should never depend on the value of
231 <symbol>*default-database*</symbol> and should provide
232 correct database objects via the
233 <parameter>database</parameter> parameter to functions
239 <refentry id="default-database-type">
241 <refentrytitle>*DEFAULT-DATABASE-TYPE*</refentrytitle>
244 <refname><emphasis>Variable</emphasis> <emphasis role="bold">*DEFAULT-DATABASE-TYPE*</emphasis></refname>
245 <refpurpose>The default database type to use</refpurpose>
246 <refclass>Variable</refclass>
249 <title>Value Type</title>
250 <para>Any keyword representing a valid database back-end of
251 &clsql;, or &nil;.</para>
254 <title>Initial Value</title>
258 <title>Description</title>
259 <para>The value of this variable is used in calls to
260 <function>initialize-database-type</function> and
261 <function>connect</function> as the default value of the
262 <parameter>database-type</parameter> parameter.</para>
264 <para>If the value of this variable is &nil;,
266 <function>initialize-database-type</function> or
267 <function>connect</function> will have to specify the
268 <parameter>database-type</parameter> to use, or a
269 general-purpose error will be signalled.</para>
273 <title>Examples</title>
275 (setf *default-database-type* :mysql)
277 (initialize-database-type)
282 <title>Affected By</title>
286 <title>See Also</title>
289 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
298 <refentry id="initialized-database-types">
300 <refentrytitle>*INITIALIZED-DATABASE-TYPES*</refentrytitle>
303 <refname><emphasis>Variable</emphasis> <emphasis role="bold">*INITIALIZED-DATABASE-TYPES*</emphasis></refname>
304 <refpurpose>List of all initialized database types</refpurpose>
305 <refclass>Variable</refclass>
308 <title>Value Type</title>
309 <para>A list of all initialized database types, each of which
310 represented by it's corresponding keyword.</para>
313 <title>Initial Value</title>
317 <title>Description</title>
318 <para>This variable is updated whenever
319 <function>initialize-database-type</function> is called for a
320 database type which hasn't already been initialized before, as
321 determined by this variable. In that case the keyword
322 representing the database type is pushed onto the list stored in
323 <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
325 <para>Attempts to modify the value of this variable will
326 result in undefined behaviour.</para>
330 <title>Examples</title>
332 (setf *default-database-type* :mysql)
334 (initialize-database-type)
336 *initialized-database-types*
341 <title>Affected By</title>
344 <member><function>initialize-database-type</function></member>
349 <title>See Also</title>
352 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
357 <para>Direct access to this variable is primarily provided
358 because of compatibility with Harlequin's <application>Common
359 SQL</application>.</para>
363 <refentry id="connect">
365 <refentrytitle>CONNECT</refentrytitle>
368 <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECT</emphasis></refname>
369 <refpurpose>create a connection to a database.</refpurpose>
370 <refclass>Function</refclass>
373 <title>Syntax</title>
374 <title>Syntax</title>
375 <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>
378 <title>Arguments and Values</title>
381 <term><parameter>connection-spec</parameter></term>
383 <para>A vendor specific connection specification supplied
384 as a list or as a string.</para>
388 <term><parameter>if-exists</parameter></term>
390 <para>This indicates the action to take if a connection
391 to the same database exists already. See below for the
392 legal values and actions. It defaults to the value of
393 <symbol>*connect-if-exists*</symbol>.</para>
397 <term><parameter>database-type</parameter></term>
399 <para>A database type specifier, i.e. a keyword.
400 This defaults to the value of
401 <symbol>*default-database-type*</symbol></para>
405 <term><parameter>pool</parameter></term>
407 <para>A boolean flag. If &t;, acquire connection from a
408 pool of open connections. If the pool is empty, a new
409 connection is created. The default is &nil;.
414 <term><parameter>make-default</parameter></term>
416 <para>A boolean flag. If &t;,
417 <symbol>*default-database*</symbol> is set to the new
418 connection, otherwise <symbol>*default-database*</symbol>
419 is not changed. The default is &t;.
424 <term><returnvalue>database</returnvalue></term>
426 <para>The database object representing the connection.</para>
432 <title>Description</title>
433 <para>This function takes a connection specification and
434 a database type and creates a connection to the database
435 specified by those. The type and structure of the
436 connection specification depend on the database type.</para>
437 <para>The parameter <parameter>if-exists</parameter> specifies
438 what to do if a connection to the database specified exists
439 already, which is checked by calling
440 <function>find-database</function> on the database name
441 returned by <function>database-name-from-spec</function>
442 when called with the <parameter>connection-spec</parameter>
443 and <parameter>database-type</parameter> parameters. The
444 possible values of <parameter>if-exists</parameter> are:
447 <term><symbol>:new</symbol></term>
449 <para>Go ahead and create a new connection.</para>
453 <term><symbol>:warn-new</symbol></term>
455 <para>This is just like <symbol>:new</symbol>, but
456 also signals a warning of type
457 <errortype>clsql-exists-warning</errortype>,
458 indicating the old and newly created
463 <term><symbol>:error</symbol></term>
465 <para>This will cause <function>connect</function> to
466 signal a correctable error of type
467 <errortype>clsql-exists-error</errortype>. The
468 user may choose to proceed, either by indicating
469 that a new connection shall be created, via the
470 restart <symbol>create-new</symbol>, or by
471 indicating that the existing connection shall be
472 used, via the restart
473 <symbol>use-old</symbol>.</para>
477 <term><symbol>:old</symbol></term>
479 <para>This will cause <function>connect</function> to
480 use an old connection if one exists.</para>
484 <term><symbol>:warn-old</symbol></term>
486 <para>This is just like <symbol>:old</symbol>, but
487 also signals a warning of type
488 <errortype>clsql-exists-warning</errortype>,
489 indicating the old database used, via the slots
490 <symbol>old-db</symbol> and
491 <symbol>new-db</symbol></para>
496 <para>The database name of the returned database object will
497 be the same under <function>string=</function> as that which
498 would be returned by a call to
499 <function>database-name-from-spec</function> with the given
500 <parameter>connection-spec</parameter> and
501 <parameter>database-type</parameter> parameters.</para>
504 <title>Examples</title>
506 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
507 => "dent/newesim/dent"
508 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
509 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
511 => "dent/newesim/dent"
513 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
514 >> In call to CONNECT:
515 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
518 >> 0: [CREATE-NEW] Create a new connection.
519 >> 1: [USE-OLD ] Use the existing connection.
520 >> 2: [ABORT ] Return to Top-Level.
522 >> Debug (type H for help)
524 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
526 >> ; File: /prj/CLSQL/sql/sql.cl
527 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
528 >> (CREATE-NEW NIL :REPORT "Create a new connection."
530 >> (USE-OLD NIL :REPORT "Use the existing connection."
531 >> (SETQ RESULT OLD-DB)))
533 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
537 <title>Side Effects</title>
538 <para>A database connection is established, and the resultant
539 database object is registered, so as to appear in the list
540 returned by <function>connected-databases</function>.
541 <symbol>*default-database*</symbol> may be rebound to the
542 created object.</para>
545 <title>Affected by</title>
548 <member><symbol>*default-database-type*</symbol></member>
549 <member><symbol>*connect-if-exists*</symbol></member>
554 <title>Exceptional Situations</title>
555 <para>If the connection specification is not syntactically or
556 semantically correct for the given database type, an error of
557 type <errortype>sql-user-error</errortype> is
558 signalled. If during the connection attempt an error is
559 detected (e.g. because of permission problems, network trouble
560 or any other cause), an error of type
561 <errortype>sql-database-error</errortype> is signalled.</para>
562 <para>If a connection to the database specified by
563 <parameter>connection-spec</parameter> exists already,
564 conditions are signalled according to the
565 <parameter>if-exists</parameter> parameter, as described
569 <title>See Also</title>
571 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
572 <member><link linkend="disconnect"><function>disconnect</function></link></member>
573 <member><link linkend="reconnect"><function>reconnect</function></link></member>
574 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
575 <member><link linkend="find-database"><function>find-database</function></link></member>
576 <member><link linkend="status"><function>status</function></link></member>
581 <para>The <parameter>pool</parameter> and
582 <parameter>make-default</parameter> keyword arguments to
583 <function>connect</function> are &clsql; extensions.</para>
587 <refentry id="connected-databases">
589 <refentrytitle>CONNECTED-DATABASES</refentrytitle>
592 <refname><emphasis>Function</emphasis> <emphasis role="bold">CONNECTED-DATABASES</emphasis></refname>
593 <refpurpose>Return the list of active database objects.</refpurpose>
594 <refclass>Function</refclass>
597 <title>Syntax</title>
599 <function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
602 <title>Arguments and Values</title>
605 <term><returnvalue>databases</returnvalue></term>
607 <para>The list of active database objects.</para>
613 <title>Description</title>
614 <para>This function returns the list of active database
615 objects, i.e. all those database objects created by calls to
616 <function>connect</function>, which have not been closed by
617 calling <function>disconnect</function> on them.</para>
619 <para>The consequences of modifying the list returned by
620 <function>connected-databases</function> are
625 <title>Examples</title>
627 (connected-databases)
629 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
630 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
631 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
632 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
633 (connected-databases)
634 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
635 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
638 (connected-databases)
639 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
642 (connected-databases)
647 <title>Side Effects</title>
651 <title>Affected By</title>
654 <member><function>connect</function></member>
655 <member><function>disconnect</function></member>
660 <title>Exceptional Situations</title>
664 <title>See Also</title>
666 <member><link linkend="disconnect"><function>disconnect</function></link></member>
667 <member><link linkend="connect"><function>connect</function></link></member>
668 <member><link linkend="status"><function>status</function></link></member>
669 <member><link linkend="find-database"><function>find-database</function></link></member>
679 <refentry id="database-name">
681 <refentrytitle>DATABASE-NAME</refentrytitle>
684 <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME</emphasis></refname>
685 <refpurpose>Get the name of a database object</refpurpose>
686 <refclass>Generic Function</refclass>
689 <title>Syntax</title>
690 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
693 <title>Arguments and Values</title>
696 <term><parameter>database</parameter></term>
698 <para>A database object, either of type
699 <type>database</type> or of type
700 <type>closed-database</type>.</para>
704 <term><returnvalue>name</returnvalue></term>
706 <para>A string describing the identity of the database
707 to which this database object is connected to.</para>
713 <title>Description</title>
714 <para>This function returns the database name of the given
715 database. The database name is a string which somehow
716 describes the identity of the database to which this
717 database object is or has been connected. The database name
718 of a database object is determined at
719 <function>connect</function> time, when a call to
720 <function>database-name-from-spec</function> derives the
721 database name from the connection specification passed to
722 <function>connect</function> in the
723 <parameter>connection-spec</parameter> parameter.</para>
724 <para>The database name is used via
725 <function>find-database</function> in
726 <function>connect</function> to determine whether database
727 connections to the specified database exist already.</para>
728 <para>Usually the database name string will include
729 indications of the host, database name, user, or port that
730 where used during the connection attempt. The only
731 important thing is that this string shall try to identify
732 the database at the other end of the connection. Connection
733 specifications parts like passwords and credentials shall
734 not be used as part of the database name.</para>
737 <title>Examples</title>
739 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
740 => "dent/newesim/dent"
741 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
742 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
743 (database-name *default-database*)
744 => "dent/newesim/dent"
746 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
748 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
749 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
750 (database-name *default-database*)
753 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
754 => "www.pmsf.de/template1/dent"
758 <title>Side Effects</title>
762 <title>Affected By</title>
765 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
770 <title>Exceptional Situations</title>
771 <para>Will signal an error if the object passed as the
772 <parameter>database</parameter> parameter is neither of type
773 <type>database</type> nor of type
774 <type>closed-database</type>.</para>
777 <title>See Also</title>
781 linkend="connect"><function>connect</function></link></member>
783 linkend="find-database"><function>find-database</function></link></member>
784 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
785 <member><link linkend="disconnect"><function>disconnect</function></link></member>
786 <member><link linkend="status"><function>status</function></link></member>
796 <refentry id="database-name-from-spec">
798 <refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
801 <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-NAME-FROM-SPEC</emphasis></refname>
802 <refpurpose>Return the database name string corresponding to
803 the given connection specification.</refpurpose>
804 <refclass>Generic Function</refclass>
807 <title>Syntax</title>
809 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
812 <title>Arguments and Values</title>
815 <term><parameter>connection-spec</parameter></term>
817 <para>A connection specification, whose structure and
818 interpretation are dependent on the
819 <parameter>database-type</parameter>.</para>
823 <term><parameter>database-type</parameter></term>
825 <para>A database type specifier, i.e. a keyword.</para>
829 <term><returnvalue>name</returnvalue></term>
831 <para>A string denoting a database name.</para>
837 <title>Description</title>
838 <para>This generic function takes a connection specification
839 and a database type and returns the database name of the
840 database object that would be created had
841 <function>connect</function> been called with the given
842 connection specification and database types.</para>
843 <para>This function is useful in determining a database name
844 from the connection specification, since the way the
845 connection specification is converted into a database name
846 is dependent on the database type.</para>
849 <title>Examples</title>
851 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
852 => "dent/newesim/dent"
853 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
854 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
855 (database-name *default-database*)
856 => "dent/newesim/dent"
858 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
860 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
861 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
862 (database-name *default-database*)
865 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
866 => "www.pmsf.de/template1/dent"
868 (find-database "dent/newesim/dent")
869 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
870 (find-database "/template1/dent")
871 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
872 (find-database "www.pmsf.de/template1/dent" nil)
875 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
879 <title>Side Effects</title>
883 <title>Affected by</title>
887 <title>Exceptional Situations</title>
888 <para>If the value of <parameter>connection-spec</parameter>
889 is not a valid connection specification for the given
890 database type, an error of type
891 <errortype>clsql-invalid-spec-error</errortype> might be
895 <title>See Also</title>
898 <member><link linkend="connect"><function>connect</function></link></member>
904 <para><function>database-name-from-spec</function> is a
905 &clsql; extension.</para>
909 <refentry id="database-type">
911 <refentrytitle>DATABASE-TYPE</refentrytitle>
914 <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">DATABASE-TYPE</emphasis></refname>
915 <refpurpose>Get the type of a database object.</refpurpose>
916 <refclass>Generic Function</refclass>
919 <title>Syntax</title>
921 <function>database-type</function> <replaceable>DATABASE</replaceable> => <returnvalue>type</returnvalue></synopsis>
924 <title>Arguments and Values</title>
927 <term><parameter>database</parameter></term>
929 <para>A database object, either of type
930 <type>database</type> or of type
931 <type>closed-database</type>.</para>
935 <term><returnvalue>type</returnvalue></term>
937 <para>A keyword symbol denoting a known database back-end.</para>
943 <title>Description</title>
945 Returns the type of <parameter>database</parameter>.
949 <title>Examples</title>
951 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
952 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
953 (database-type *default-database*)
958 <title>Side Effects</title>
964 <title>Affected by</title>
970 <title>Exceptional Situations</title>
971 <para>Will signal an error if the object passed as the
972 <parameter>database</parameter> parameter is neither of type
973 <type>database</type> nor of type
974 <type>closed-database</type>.</para>
977 <title>See Also</title>
981 linkend="connect"><function>connect</function></link></member>
983 linkend="find-database"><function>find-database</function></link></member>
984 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
985 <member><link linkend="disconnect"><function>disconnect</function></link></member>
986 <member><link linkend="status"><function>status</function></link></member>
993 <function>database-type</function> is a &clsql; extension.
998 <refentry id="disconnect">
1000 <refentrytitle>DISCONNECT</refentrytitle>
1003 <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT</emphasis></refname>
1004 <refpurpose>close a database connection</refpurpose>
1005 <refclass>Function</refclass>
1008 <title>Syntax</title>
1009 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>error</replaceable> => <returnvalue>result</returnvalue></synopsis>
1012 <title>Arguments and Values</title>
1015 <term><parameter>error</parameter></term>
1017 <para>A boolean flag indicating whether to signal an error
1018 if <parameter>database</parameter> is non-&nil; but cannot
1024 <term><parameter>database</parameter></term>
1026 <para>The database to disconnect, which defaults to the
1027 database indicated by
1028 <symbol>*default-database*</symbol>.</para>
1032 <term><parameter>result</parameter></term>
1034 <para>A Boolean indicating whether a connection was
1035 successfully disconnected.
1042 <title>Description</title>
1043 <para>This function takes a <type>database</type> object as
1044 returned by <function>connect</function>, and closes the
1045 connection. If no matching database is found and
1046 <parameter>error</parameter> and
1047 <parameter>database</parameter> are both non-&nil; an error is
1048 signaled, otherwise &nil; is returned. If the database is from a
1049 pool it will be released to this pool.
1052 <para>The status of the object passed is changed to closed
1053 after the disconnection succeeds, thereby preventing further
1054 use of the object as an argument to &clsql; functions, with
1055 the exception of <function>database-name</function> and
1056 <function>database-type</function>. If the user does pass a
1057 closed database to any other &clsql; function, an error of
1058 type <errortype>sql-fatal-error</errortype> is
1062 <title>Examples</title>
1064 (disconnect :database (find-database "dent/newesim/dent"))
1069 <title>Side Effects</title>
1070 <para>The database connection is closed, and the database
1071 object is removed from the list of connected databases as
1072 returned by <function>connected-databases</function>.</para>
1073 <para>The state of the database object is changed to
1074 <type>closed</type>.</para>
1075 <para>If the database object passed is the same under
1076 <function>eq</function> as the value of
1077 <symbol>*default-database*</symbol>, then
1078 <symbol>*default-database*</symbol> is set to the first
1079 remaining database from
1080 <function>connected-databases</function> or to &nil; if no
1081 further active database exists.</para>
1084 <title>Affected by</title>
1087 <member><symbol>*default-database*</symbol></member>
1092 <title>Exceptional Situations</title>
1093 <para>If during the disconnection attempt an error is detected
1094 (e.g. because of network trouble or any other cause), an error
1095 of type <errortype>sql-error</errortype> might be
1099 <title>See Also</title>
1102 <member><link linkend="connect"><function>connect</function></link></member>
1103 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1108 <title>Notes</title>
1113 <refentry id="disconnect-pooled">
1115 <refentrytitle>DISCONNECT-POOLED</refentrytitle>
1118 <refname><emphasis>Function</emphasis> <emphasis role="bold">DISCONNECT-POOLED</emphasis></refname>
1119 <refpurpose>closes all pooled database connections</refpurpose>
1120 <refclass>Function</refclass>
1123 <title>Syntax</title>
1124 <synopsis><function>disconnect-pooled</function> => <returnvalue>t</returnvalue></synopsis>
1127 <title>Description</title>
1128 <para>This function disconnects all database connections
1129 that have been placed into the pool by calling <link
1130 linkend="connect"><function>connect</function></link> with
1135 <title>Examples</title>
1142 <title>Side Effects</title>
1143 <para>Database connections will be closed and entries in the pool are removed.
1147 <title>Affected by</title>
1150 <member><function>disconnect</function></member>
1155 <title>Exceptional Situations</title>
1156 <para>If during the disconnection attempt an error is
1157 detected (e.g. because of network trouble or any other
1158 cause), an error of type <errortype>clsql-error</errortype>
1159 might be signalled.</para>
1162 <title>See Also</title>
1165 <member><link linkend="connect"><function>connect</function></link></member>
1166 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1171 <title>Notes</title>
1172 <para><function>disconnect-pooled</function> is a &clsql;
1177 <refentry id="find-database">
1179 <refentrytitle>FIND-DATABASE</refentrytitle>
1182 <refname><emphasis>Function</emphasis> <emphasis role="bold">FIND-DATABASE</emphasis></refname>
1183 <refpurpose>>Locate a database object through it's
1185 <refclass>Function</refclass>
1188 <title>Syntax</title>
1189 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1192 <title>Arguments and Values</title>
1195 <term><parameter>database</parameter></term>
1197 <para>A database object or a string, denoting a database
1202 <term><parameter>errorp</parameter></term>
1204 <para>A generalized boolean. Defaults to
1205 <symbol>t</symbol>.</para>
1209 <term><parameter>db-type</parameter></term>
1212 A keyword symbol denoting a known database back-end.
1217 <term><returnvalue>result</returnvalue></term>
1219 <para>Either a database object, or, if
1220 <parameter>errorp</parameter> is &nil;,
1221 possibly &nil;.</para>
1227 <title>Description</title>
1228 <para><function>find-database</function> locates an active
1229 database object given the specification in
1230 <parameter>database</parameter>. If
1231 <parameter>database</parameter> is an object of type
1232 <type>database</type>, <function>find-database</function>
1233 returns this. Otherwise it will search the active databases
1234 as indicated by the list returned by
1235 <function>connected-databases</function> for a database of
1236 type <parameter>db-type</parameter> whose name (as returned by
1237 <function>database-name</function> is equal as per
1238 <function>string=</function> to the string passed as
1239 <parameter>database</parameter>. If it succeeds, it returns
1240 the first database found.</para>
1242 If <parameter>db-type</parameter> is &nil; all databases
1243 matching the string <parameter>database</parameter> are
1244 considered. If no matching databases are found and
1245 <parameter>errorp</parameter> is &nil; then &nil; is
1246 returned. If <parameter>errorp</parameter> is &nil; and one or
1247 more matching databases are found, then the most recently
1248 connected database is returned as a first value and the
1249 number of matching databases is returned as a second
1250 value. If no, or more than one, matching databases are found
1251 and <parameter>errorp</parameter> is true, an error is
1256 <title>Examples</title>
1258 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1259 => "dent/newesim/dent"
1260 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1261 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1262 (database-name *default-database*)
1263 => "dent/newesim/dent"
1265 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1266 => "/template1/dent"
1267 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1268 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1269 (database-name *default-database*)
1270 => "/template1/dent"
1272 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1273 => "www.pmsf.de/template1/dent"
1275 (find-database "dent/newesim/dent")
1276 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1277 (find-database "/template1/dent")
1278 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1279 (find-database "www.pmsf.de/template1/dent" nil)
1282 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1286 <title>Side Effects</title>
1290 <title>Affected By</title>
1293 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1298 <title>Exceptional Situations</title>
1299 <para>Will signal an error of type
1300 <errortype>clsql-error</errortype> if no matching database
1301 can be found, and <parameter>errorp</parameter> is true.
1302 Will signal an error if the value of
1303 <parameter>database</parameter> is neither an object of type
1304 <type>database</type> nor a string.</para>
1307 <title>See Also</title>
1311 linkend="database-name"><function>database-name</function></link></member>
1313 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1314 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1315 <member><link linkend="connect"><function>connect</function></link></member>
1316 <member><link linkend="status"><function>status</function></link></member>
1317 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1322 <title>Notes</title>
1323 <para>The <parameter>db-type</parameter> keyword argument to
1324 <function>find-database</function> is a &clsql;
1329 <refentry id="initialize-database-type">
1331 <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
1334 <refname><emphasis>Function</emphasis> <emphasis role="bold">INITIALIZE-DATABASE-TYPE</emphasis></refname>
1335 <refpurpose>Initializes a database type</refpurpose>
1336 <refclass>Function</refclass>
1339 <title>Syntax</title>
1341 <function>initialize-database-type &key database-type</function> => <returnvalue>result</returnvalue></synopsis>
1344 <title>Arguments and Values</title>
1347 <term><parameter>database-type</parameter></term>
1349 <para>The database type to initialize, i.e. a keyword
1350 symbol denoting a known database back-end. Defaults to
1352 <symbol>*default-database-type*</symbol>.</para>
1356 <term><returnvalue>result</returnvalue></term>
1358 <para>Either &nil; if the initialization
1359 attempt fails, or <symbol>t</symbol> otherwise.</para>
1365 <title>Description</title>
1366 <para>If the back-end specified by
1367 <parameter>database-type</parameter> has not already been
1368 initialized, as seen from
1369 <symbol>*initialized-database-types*</symbol>, an attempt is
1370 made to initialize the database. If this attempt succeeds,
1371 or the back-end has already been initialized, the function
1372 returns t, and places the keyword denoting the database type
1373 onto the list stored in
1374 <symbol>*initialized-database-types*</symbol>, if not
1375 already present.</para>
1376 <para>If initialization fails, the function returns
1377 &nil;, and/or signals an error of type
1378 <errortype>clsql-error</errortype>. The kind of action
1379 taken depends on the back-end and the cause of the
1383 <title>Examples</title>
1385 *initialized-database-types*
1387 (setf *default-database-type* :mysql)
1389 (initialize-database-type)
1390 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
1391 >> Compiling Top-Level Form:
1394 *initialized-database-types*
1396 (initialize-database-type)
1398 *initialized-database-types*
1403 <title>Side Effects</title>
1404 <para>The database back-end corresponding to the database type
1405 specified is initialized, unless it has already been
1406 initialized. This can involve any number of other side
1407 effects, as determined by the back-end implementation (like
1408 e.g. loading of foreign code, calling of foreign code,
1409 networking operations, etc.). If initialization is
1410 attempted and succeeds, the
1411 <parameter>database-type</parameter> is pushed onto the list
1413 <symbol>*initialized-database-types*</symbol>.</para>
1416 <title>Affected by</title>
1419 <member><symbol>*default-database-type*</symbol></member>
1420 <member><symbol>*initialized-database-types*</symbol></member>
1425 <title>Exceptional Situations</title>
1426 <para>If an error is encountered during the initialization
1427 attempt, the back-end may signal errors of kind
1428 <errortype>clsql-error</errortype>.</para>
1431 <title>See Also</title>
1433 <member><link linkend="initialized-database-types"><function>*initialized-database-types*</function></link></member>
1434 <member><link linkend="default-database-type"><function>*default-database-type*</function></link></member>
1438 <title>Notes</title>
1443 <refentry id="reconnect">
1445 <refentrytitle>RECONNECT</refentrytitle>
1448 <refname><emphasis>Function</emphasis> <emphasis role="bold">RECONNECT</emphasis></refname>
1449 <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
1450 <refclass>Function</refclass>
1453 <title>Syntax</title>
1455 <function>reconnect</function> &key <parameter>database</parameter> <parameter>error</parameter> <parameter>force</parameter> => <returnvalue>result</returnvalue></synopsis>
1458 <title>Arguments and Values</title>
1461 <term><parameter>database</parameter></term>
1463 <para>The database to reconnect, which defaults to the
1464 database indicated by
1465 <symbol>*default-database*</symbol>.</para>
1469 <term><parameter>error</parameter></term>
1471 <para>A boolean flag indicating whether to signal an error
1472 if <parameter>database</parameter> is non-nil but cannot
1473 be found. The default value is &nil;.
1478 <term><parameter>force</parameter></term>
1480 <para>A Boolean indicating whether to signal an error if the
1481 database connection has been lost. The default value is &t;.
1486 <term><parameter>result</parameter></term>
1488 <para>A Boolean indicating whether the database was
1489 successfully reconnected.
1496 <title>Description</title>
1497 <para>Reconnects <parameter>database</parameter> which defaults
1498 to <symbol>*default-database*</symbol> to the underlying
1499 database management system. On success, &t; is returned and the
1500 variable <symbol>*default-database*</symbol> is set to the newly
1501 reconnected database. If <parameter>database</parameter> is a
1502 database instance, this object is closed. If
1503 <parameter>database</parameter> is a string, then a connected
1504 database whose name matches <parameter>database</parameter> is
1505 sought in the list of connected databases. If no matching
1506 database is found and <parameter>error</parameter> and
1507 <parameter>database</parameter> are both non-&nil; an error is
1508 signaled, otherwise &nil; is returned.</para>
1510 <para> When the current database connection has been lost, if
1511 <parameter>force</parameter> is non-&nil; as it is by default, the
1512 connection is closed and errors are suppressed. If
1513 <parameter>force</parameter> is &nil; and the database connection
1514 cannot be closed, an error is signalled.
1518 <title>Examples</title>
1521 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}>
1523 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}>
1527 <title>Side Effects</title>
1528 <para>A database connection is re-established and
1529 <symbol>*default-database*</symbol> may be rebound to the supplied
1530 database object.</para>
1533 <title>Affected by</title>
1536 <member><symbol>*default-database*</symbol></member>
1541 <title>Exceptional Situations</title>
1543 An error may be signalled if the specified database cannot be
1544 located or if the database cannot be closed.
1548 <title>See Also</title>
1552 linkend="connect"><function>connect</function></link></member>
1554 linkend="disconnect"><function>disconnect</function></link></member>
1556 linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1561 <title>Notes</title>
1568 <refentry id="status">
1570 <refentrytitle>STATUS</refentrytitle>
1573 <refname><emphasis>Function</emphasis> <emphasis role="bold">STATUS</emphasis></refname>
1574 <refpurpose>Print information about connected databases.</refpurpose>
1575 <refclass>Function</refclass>
1578 <title>Syntax</title>
1580 <function>status</function> &optional <parameter>full</parameter> => <returnvalue></returnvalue></synopsis>
1583 <title>Arguments and Values</title>
1586 <term><parameter>full</parameter></term>
1588 <para>A boolean indicating whether to print additional
1589 table information. The default value is &nil;.
1596 <title>Description</title>
1597 <para>Prints information about the currently connected databases
1598 to <symbol>*STANDARD-OUTPUT*</symbol>. The argument
1599 <parameter>full</parameter> is &nil; by default and a value of t
1600 means that more detailed information about each database is
1605 <title>Examples</title>
1609 CLSQL STATUS: 2004-06-13 15:07:39
1610 --------------------------------------------------------
1611 DATABASE TYPE RECORDING
1612 --------------------------------------------------------
1613 localhost/test/petrov mysql nil
1614 localhost/test/petrov postgresql nil
1615 localhost/test/petrov postgresql-socket nil
1616 test/petrov odbc nil
1617 * :memory: sqlite nil
1618 --------------------------------------------------------
1622 CLSQL STATUS: 2004-06-13 15:08:08
1623 -------------------------------------------------------------------------------
1624 DATABASE TYPE RECORDING POOLED TABLES VIEWS
1625 -------------------------------------------------------------------------------
1626 localhost/test/petrov mysql nil nil 7 0
1627 localhost/test/petrov postgresql nil nil 7 0
1628 localhost/test/petrov postgresql-socket nil nil 7 0
1629 test/petrov odbc nil nil 7 0
1630 * :memory: sqlite nil nil 0 0
1631 -------------------------------------------------------------------------------
1635 <title>Side Effects</title>
1641 <title>Affected by</title>
1647 <title>Exceptional Situations</title>
1653 <title>See Also</title>
1656 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1657 <member><link linkend="connect"><function>connect</function></link></member>
1658 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1659 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
1660 <member><link linkend="find-database"><function>find-database</function></link></member>
1665 <title>Notes</title>
1673 <!-- create/probe/list/destroytruncate-database -->
1675 <refentry id="create-database">
1677 <refentrytitle>CREATE-DATABASE</refentrytitle>
1680 <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-DATABASE</emphasis></refname>
1681 <refpurpose>create a database</refpurpose>
1682 <refclass>Function</refclass>
1685 <title>Syntax</title>
1686 <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1689 <title>Arguments and Values</title>
1692 <term><parameter>connection-spec</parameter></term>
1694 <para>A connection specification</para>
1698 <term><parameter>database-type</parameter></term>
1700 <para>A database type specifier, i.e. a keyword.
1701 This defaults to the value of
1702 <symbol>*default-database-type*</symbol></para>
1706 <term><parameter>success</parameter></term>
1708 <para>A boolean flag. If &t;, a new database was
1709 successfully created.
1716 <title>Description</title>
1717 <para>This function creates a database in the database system
1718 specified by <parameter>database-type</parameter>.
1722 <title>Examples</title>
1724 (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
1727 (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
1729 Error: While trying to access database localhost/new/dent
1730 using database-type MYSQL:
1731 Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1732 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1734 [condition type: CLSQL-ACCESS-ERROR]
1738 <title>Side Effects</title>
1739 <para>A database will be created on the filesystem of the host.</para>
1742 <title>Exceptional Situations</title>
1743 <para>An exception will be thrown if the database system does
1744 not allow new databases to be created or if database creation
1748 <title>See Also</title>
1751 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1752 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1753 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1758 <title>Notes</title>
1759 <para>This function may invoke the operating systems
1760 functions. Thus, some database systems may require the
1761 administration functions to be available in the current
1762 <symbol>PATH</symbol>. At this time, the
1763 <symbol>:mysql</symbol> backend requires
1764 <filename>mysqladmin</filename> and the
1765 <symbol>:postgresql</symbol> backend requires
1766 <filename>createdb</filename>.</para>
1768 <function>create-database</function> is a &clsql; extension.
1773 <refentry id="destroy-database">
1775 <refentrytitle>DESTROY-DATABASE</refentrytitle>
1778 <refname><emphasis>Function</emphasis> <emphasis role="bold">DESTROY-DATABASE</emphasis></refname>
1779 <refpurpose>destroys a database</refpurpose>
1780 <refclass>Function</refclass>
1783 <title>Syntax</title>
1784 <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1787 <title>Arguments and Values</title>
1790 <term><parameter>connection-spec</parameter></term>
1792 <para>A connection specification</para>
1796 <term><parameter>database-type</parameter></term>
1798 <para>A database type specifier, i.e. a keyword.
1799 This defaults to the value of
1800 <symbol>*default-database-type*</symbol></para>
1804 <term><parameter>success</parameter></term>
1806 <para>A boolean flag. If &t;, the database was
1807 successfully destroyed.
1814 <title>Description</title>
1815 <para>This function destroys a database in the database system
1816 specified by <parameter>database-type</parameter>.
1820 <title>Examples</title>
1822 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1825 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1827 Error: While trying to access database localhost/test2/root
1828 using database-type POSTGRESQL:
1829 Error database-destory failed: dropdb: database removal failed: ERROR: database "test2" does not exist
1831 [condition type: CLSQL-ACCESS-ERROR]
1835 <title>Side Effects</title>
1836 <para>A database will be removed from the filesystem of the host.</para>
1839 <title>Exceptional Situations</title>
1840 <para>An exception will be thrown if the database system does not
1841 allow databases to be removed, the database does not exist, or
1842 if database removal fails.</para>
1845 <title>See Also</title>
1848 <member><link linkend="create-database"><function>create-database</function></link></member>
1849 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1850 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1855 <title>Notes</title>
1856 <para>This function may invoke the operating systems
1857 functions. Thus, some database systems may require the
1858 administration functions to be available in the current
1859 <symbol>PATH</symbol>. At this time, the
1860 <symbol>:mysql</symbol> backend requires
1861 <filename>mysqladmin</filename> and the
1862 <symbol>:postgresql</symbol> backend requires
1863 <filename>dropdb</filename>.</para>
1865 <function>destroy-database</function> is a &clsql; extension.
1870 <refentry id="probe-database">
1872 <refentrytitle>PROBE-DATABASE</refentrytitle>
1875 <refname><emphasis>Function</emphasis> <emphasis role="bold">PROBE-DATABASE</emphasis></refname>
1876 <refpurpose>tests for existence of a database</refpurpose>
1877 <refclass>Function</refclass>
1880 <title>Syntax</title>
1881 <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1884 <title>Arguments and Values</title>
1887 <term><parameter>connection-spec</parameter></term>
1889 <para>A connection specification</para>
1893 <term><parameter>database-type</parameter></term>
1895 <para>A database type specifier, i.e. a keyword.
1896 This defaults to the value of
1897 <symbol>*default-database-type*</symbol></para>
1901 <term><parameter>success</parameter></term>
1903 <para>A boolean flag. If &t;, the database exists
1904 in the database system.
1911 <title>Description</title>
1912 <para>This function tests for the existence of a database in
1913 the database system specified by
1914 <parameter>database-type</parameter>.
1918 <title>Examples</title>
1920 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1925 <title>Side Effects</title>
1929 <title>Exceptional Situations</title>
1930 <para>An exception maybe thrown if the database system does
1931 not receive administrator-level authentication since function
1932 may need to read the administrative database of the database
1936 <title>See Also</title>
1939 <member><link linkend="create-database"><function>create-database</function></link></member>
1940 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1941 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1946 <title>Notes</title>
1948 <function>probe-database</function> is a &clsql; extension.
1953 <refentry id="list-databases">
1955 <refentrytitle>LIST-DATABASES</refentrytitle>
1958 <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-DATABASES</emphasis></refname>
1959 <refpurpose>List databases matching the supplied connection spec
1960 and database type.</refpurpose>
1961 <refclass>Function</refclass>
1964 <title>Syntax</title>
1966 <function>list-databases</function> <parameter>connection-spec</parameter> &key <parameter>database-type</parameter> => <returnvalue>result</returnvalue></synopsis>
1969 <title>Arguments and Values</title>
1972 <term><parameter>connection-spec</parameter></term>
1974 <para>A connection specification</para>
1978 <term><parameter>database-type</parameter></term>
1980 <para>A database type specifier, i.e. a keyword.
1981 This defaults to the value of
1982 <symbol>*default-database-type*</symbol></para>
1986 <term><parameter>result</parameter></term>
1988 <para>A list of matching databases.
1995 <title>Description</title>
1997 This function returns a list of databases existing in the
1998 database system specified by
1999 <parameter>database-type</parameter>.
2003 <title>Examples</title>
2005 (list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql)
2006 => ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test")
2010 <title>Side Effects</title>
2016 <title>Affected by</title>
2022 <title>Exceptional Situations</title>
2024 An exception maybe thrown if the database system does not
2025 receive administrator-level authentication since function may
2026 need to read the administrative database of the database
2031 <title>See Also</title>
2034 <member><link linkend="create-database"><function>create-database</function></link></member>
2035 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2036 <member><link linkend="probe-database"><function>probe-database</function></link></member>
2041 <title>Notes</title>
2043 <function>list-databases</function> is a &clsql; extension.
2049 <!-- with-database and with-default-database -->
2051 <refentry id="with-database">
2053 <refentrytitle>WITH-DATABASE</refentrytitle>
2056 <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DATABASE</emphasis></refname>
2057 <refpurpose>Execute a body of code with a variable bound to a
2058 specified database object.</refpurpose>
2059 <refclass>Macro</refclass>
2062 <title>Syntax</title>
2064 <function>with-database</function> <replaceable>db-var</replaceable> <replaceable>connection-spec</replaceable> &rest <replaceable>connect-args</replaceable> &body <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
2067 <title>Arguments and Values</title>
2070 <term><parameter>db-var</parameter></term>
2072 <para>A variable to which the specified database is bound.
2077 <term><parameter>connection-spec</parameter></term>
2079 <para>A vendor specific connection specification supplied
2080 as a list or as a string.</para>
2084 <term><parameter>connect-args</parameter></term>
2086 <para>Other optional arguments to <function>connect</function>.
2091 <term><parameter>body</parameter></term>
2093 <para>A Lisp code body.
2098 <term><parameter>result</parameter></term>
2100 <para>Determined by the result of executing the last
2101 expression in <parameter>body</parameter>.
2108 <title>Description</title>
2109 <para>Evaluate <parameter>body</parameter> in an environment,
2110 where <parameter>db-var</parameter> is bound to the database
2111 connection given by <parameter>connection-spec</parameter> and
2112 <parameter>connect-args</parameter>. The connection is
2113 automatically closed or released to the pool on exit from the
2118 <title>Examples</title>
2120 (connected-databases)
2122 (with-database (db '(":memory:") :database-type :sqlite
2126 (connected-databases)
2131 <title>Side Effects</title>
2133 See <function>connect</function> and <function>disconnect</function>.
2137 <title>Affected by</title>
2139 See <function>connect</function> and <function>disconnect</function>.
2143 <title>Exceptional Situations</title>
2145 See <function>connect</function> and <function>disconnect</function>.
2149 <title>See Also</title>
2152 <member><link linkend="connect"><function>connect</function></link></member>
2153 <member><link linkend="disconnect"><function>disconnect</function></link></member>
2154 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
2155 <member><link linkend="with-default-database"><function>with-default-database</function></link></member>
2160 <title>Notes</title>
2162 <function>with-database</function> is a &clsql; extension.
2167 <refentry id="with-default-database">
2169 <refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
2172 <refname><emphasis>Macro</emphasis> <emphasis role="bold">WITH-DEFAULT-DATABASE</emphasis></refname>
2173 <refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
2174 <refclass>Macro</refclass>
2177 <title>Syntax</title>
2179 <function>with-default-database</function> <replaceable>database</replaceable> &rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
2182 <title>Arguments and Values</title>
2185 <term><parameter>database</parameter></term>
2187 <para>An active database object.
2192 <term><parameter>body</parameter></term>
2194 <para>A Lisp code body.
2199 <term><parameter>result</parameter></term>
2201 <para>Determined by the result of executing the last
2202 expression in <parameter>body</parameter>.
2209 <title>Description</title>
2210 <para>Perform <parameter>body</parameter> with
2211 <parameter>DATABASE</parameter> bound as
2212 <symbol>*default-database*</symbol>.
2216 <title>Examples</title>
2219 => #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}>
2221 (let ((database (clsql:find-database ":memory:")))
2222 (with-default-database (database)
2223 (database-name *default-database*)))
2228 <title>Side Effects</title>
2234 <title>Affected by</title>
2240 <title>Exceptional Situations</title>
2242 Calls to &clsql; functions in <parameter>body</parameter> may signal
2243 errors if <parameter>database</parameter> is not an active database
2248 <title>See Also</title>
2251 <member><link linkend="with-database"><function>with-database</function></link></member>
2252 <member><link linkend="default-database"><symbol>*default-database*</symbol></link></member>
2257 <title>Notes</title>
2259 <function>with-default-database</function> is a &clsql; extension.