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>DATABASE</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>*CONNECT-IF-EXISTS*</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>, that is, 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>*DEFAULT-DATABASE*</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>*DEFAULT-DATABASE-TYPE*</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>*INITIALIZED-DATABASE-TYPES*</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>CONNECT</refname>
369 <refpurpose>create a connection to a database.</refpurpose>
370 <refclass>Function</refclass>
373 <title>Syntax</title>
374 <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>
377 <title>Arguments and Values</title>
380 <term><parameter>connection-spec</parameter></term>
382 <para>A SQL backend specific connection specification
383 supplied as a list or as a string.</para>
384 <para>For the MySQL backend, this list includes an
385 optional associative list of connection options. The
386 options list is parsed and supplied to the MySQL API
387 using <function>mysql_options</function> in between the
388 calls to <function>mysql_init</function>
389 and <function>mysql_real_connect</function>.</para>
393 <term><parameter>if-exists</parameter></term>
395 <para>This indicates the action to take if a connection
396 to the same database exists already. See below for the
397 legal values and actions. It defaults to the value of
398 <symbol>*connect-if-exists*</symbol>.</para>
402 <term><parameter>database-type</parameter></term>
404 <para>A database type specifier, i.e. a keyword.
405 This defaults to the value of
406 <symbol>*default-database-type*</symbol></para>
410 <term><parameter>pool</parameter></term>
412 <para>A boolean flag. If &t;, acquire connection from a
413 pool of open connections. If the pool is empty, a new
414 connection is created. The default is &nil;.
419 <term><parameter>make-default</parameter></term>
421 <para>A boolean flag. If &t;,
422 <symbol>*default-database*</symbol> is set to the new
423 connection, otherwise <symbol>*default-database*</symbol>
424 is not changed. The default is &t;.
429 <term><returnvalue>database</returnvalue></term>
431 <para>The database object representing the connection.</para>
437 <title>Description</title>
438 <para>This function takes a connection specification and
439 a database type and creates a connection to the database
440 specified by those. The type and structure of the
441 connection specification depend on the database type.</para>
442 <para>The parameter <parameter>if-exists</parameter> specifies
443 what to do if a connection to the database specified exists
444 already, which is checked by calling
445 <function>find-database</function> on the database name
446 returned by <function>database-name-from-spec</function>
447 when called with the <parameter>connection-spec</parameter>
448 and <parameter>database-type</parameter> parameters. The
449 possible values of <parameter>if-exists</parameter> are:
452 <term><symbol>:new</symbol></term>
454 <para>Go ahead and create a new connection.</para>
458 <term><symbol>:warn-new</symbol></term>
460 <para>This is just like <symbol>:new</symbol>, but
461 also signals a warning of type
462 <errortype>clsql-exists-warning</errortype>,
463 indicating the old and newly created
468 <term><symbol>:error</symbol></term>
470 <para>This will cause <function>connect</function> to
471 signal a correctable error of type
472 <errortype>clsql-exists-error</errortype>. The
473 user may choose to proceed, either by indicating
474 that a new connection shall be created, via the
475 restart <symbol>create-new</symbol>, or by
476 indicating that the existing connection shall be
477 used, via the restart
478 <symbol>use-old</symbol>.</para>
482 <term><symbol>:old</symbol></term>
484 <para>This will cause <function>connect</function> to
485 use an old connection if one exists.</para>
489 <term><symbol>:warn-old</symbol></term>
491 <para>This is just like <symbol>:old</symbol>, but
492 also signals a warning of type
493 <errortype>clsql-exists-warning</errortype>,
494 indicating the old database used, via the slots
495 <symbol>old-db</symbol> and
496 <symbol>new-db</symbol></para>
501 <para>The database name of the returned database object will
502 be the same under <function>string=</function> as that which
503 would be returned by a call to
504 <function>database-name-from-spec</function> with the given
505 <parameter>connection-spec</parameter> and
506 <parameter>database-type</parameter> parameters.</para>
509 <title>Examples</title>
511 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
512 => "dent/newesim/dent"
513 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
514 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
516 => "dent/newesim/dent"
518 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
519 >> In call to CONNECT:
520 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
523 >> 0: [CREATE-NEW] Create a new connection.
524 >> 1: [USE-OLD ] Use the existing connection.
525 >> 2: [ABORT ] Return to Top-Level.
527 >> Debug (type H for help)
529 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
531 >> ; File: /prj/CLSQL/sql/sql.cl
532 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
533 >> (CREATE-NEW NIL :REPORT "Create a new connection."
535 >> (USE-OLD NIL :REPORT "Use the existing connection."
536 >> (SETQ RESULT OLD-DB)))
538 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
542 <title>Side Effects</title>
543 <para>A database connection is established, and the resultant
544 database object is registered, so as to appear in the list
545 returned by <function>connected-databases</function>.
546 <symbol>*default-database*</symbol> may be rebound to the
547 created object.</para>
550 <title>Affected by</title>
553 <member><symbol>*default-database-type*</symbol></member>
554 <member><symbol>*connect-if-exists*</symbol></member>
559 <title>Exceptional Situations</title>
560 <para>If the connection specification is not syntactically or
561 semantically correct for the given database type, an error of
562 type <errortype>sql-user-error</errortype> is
563 signalled. If during the connection attempt an error is
564 detected (e.g. because of permission problems, network trouble
565 or any other cause), an error of type
566 <errortype>sql-database-error</errortype> is signalled.</para>
567 <para>If a connection to the database specified by
568 <parameter>connection-spec</parameter> exists already,
569 conditions are signalled according to the
570 <parameter>if-exists</parameter> parameter, as described
574 <title>See Also</title>
576 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
577 <member><link linkend="disconnect"><function>disconnect</function></link></member>
578 <member><link linkend="reconnect"><function>reconnect</function></link></member>
579 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
580 <member><link linkend="find-database"><function>find-database</function></link></member>
581 <member><link linkend="status"><function>status</function></link></member>
586 <para>The <parameter>pool</parameter> and
587 <parameter>make-default</parameter> keyword arguments to
588 <function>connect</function> are &clsql; extensions.</para>
592 <refentry id="connected-databases">
594 <refentrytitle>CONNECTED-DATABASES</refentrytitle>
597 <refname>CONNECTED-DATABASES</refname>
598 <refpurpose>Return the list of active database objects.</refpurpose>
599 <refclass>Function</refclass>
602 <title>Syntax</title>
604 <function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
607 <title>Arguments and Values</title>
610 <term><returnvalue>databases</returnvalue></term>
612 <para>The list of active database objects.</para>
618 <title>Description</title>
619 <para>This function returns the list of active database
620 objects, i.e. all those database objects created by calls to
621 <function>connect</function>, which have not been closed by
622 calling <function>disconnect</function> on them.</para>
624 <para>The consequences of modifying the list returned by
625 <function>connected-databases</function> are
630 <title>Examples</title>
632 (connected-databases)
634 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
635 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
636 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
637 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
638 (connected-databases)
639 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
640 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
643 (connected-databases)
644 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
647 (connected-databases)
652 <title>Side Effects</title>
656 <title>Affected By</title>
659 <member><function>connect</function></member>
660 <member><function>disconnect</function></member>
665 <title>Exceptional Situations</title>
669 <title>See Also</title>
671 <member><link linkend="disconnect"><function>disconnect</function></link></member>
672 <member><link linkend="connect"><function>connect</function></link></member>
673 <member><link linkend="status"><function>status</function></link></member>
674 <member><link linkend="find-database"><function>find-database</function></link></member>
684 <refentry id="database-name">
686 <refentrytitle>DATABASE-NAME</refentrytitle>
689 <refname>DATABASE-NAME</refname>
690 <refpurpose>Get the name of a database object</refpurpose>
691 <refclass>Generic Function</refclass>
694 <title>Syntax</title>
695 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
698 <title>Arguments and Values</title>
701 <term><parameter>database</parameter></term>
703 <para>A database object, either of type
704 <type>database</type> or of type
705 <type>closed-database</type>.</para>
709 <term><returnvalue>name</returnvalue></term>
711 <para>A string describing the identity of the database
712 to which this database object is connected to.</para>
718 <title>Description</title>
719 <para>This function returns the database name of the given
720 database. The database name is a string which somehow
721 describes the identity of the database to which this
722 database object is or has been connected. The database name
723 of a database object is determined at
724 <function>connect</function> time, when a call to
725 <function>database-name-from-spec</function> derives the
726 database name from the connection specification passed to
727 <function>connect</function> in the
728 <parameter>connection-spec</parameter> parameter.</para>
729 <para>The database name is used via
730 <function>find-database</function> in
731 <function>connect</function> to determine whether database
732 connections to the specified database exist already.</para>
733 <para>Usually the database name string will include
734 indications of the host, database name, user, or port that
735 where used during the connection attempt. The only
736 important thing is that this string shall try to identify
737 the database at the other end of the connection. Connection
738 specifications parts like passwords and credentials shall
739 not be used as part of the database name.</para>
742 <title>Examples</title>
744 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
745 => "dent/newesim/dent"
746 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
747 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
748 (database-name *default-database*)
749 => "dent/newesim/dent"
751 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
753 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
754 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
755 (database-name *default-database*)
758 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
759 => "www.pmsf.de/template1/dent"
763 <title>Side Effects</title>
767 <title>Affected By</title>
770 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
775 <title>Exceptional Situations</title>
776 <para>Will signal an error if the object passed as the
777 <parameter>database</parameter> parameter is neither of type
778 <type>database</type> nor of type
779 <type>closed-database</type>.</para>
782 <title>See Also</title>
786 linkend="connect"><function>connect</function></link></member>
788 linkend="find-database"><function>find-database</function></link></member>
789 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
790 <member><link linkend="disconnect"><function>disconnect</function></link></member>
791 <member><link linkend="status"><function>status</function></link></member>
801 <refentry id="database-name-from-spec">
803 <refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
806 <refname>DATABASE-NAME-FROM-SPEC</refname>
807 <refpurpose>Return the database name string corresponding to
808 the given connection specification.</refpurpose>
809 <refclass>Generic Function</refclass>
812 <title>Syntax</title>
814 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
817 <title>Arguments and Values</title>
820 <term><parameter>connection-spec</parameter></term>
822 <para>A connection specification, whose structure and
823 interpretation are dependent on the
824 <parameter>database-type</parameter>.</para>
828 <term><parameter>database-type</parameter></term>
830 <para>A database type specifier, i.e. a keyword.</para>
834 <term><returnvalue>name</returnvalue></term>
836 <para>A string denoting a database name.</para>
842 <title>Description</title>
843 <para>This generic function takes a connection specification
844 and a database type and returns the database name of the
845 database object that would be created had
846 <function>connect</function> been called with the given
847 connection specification and database types.</para>
848 <para>This function is useful in determining a database name
849 from the connection specification, since the way the
850 connection specification is converted into a database name
851 is dependent on the database type.</para>
854 <title>Examples</title>
856 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
857 => "dent/newesim/dent"
858 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
859 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
860 (database-name *default-database*)
861 => "dent/newesim/dent"
863 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
865 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
866 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
867 (database-name *default-database*)
870 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
871 => "www.pmsf.de/template1/dent"
873 (find-database "dent/newesim/dent")
874 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
875 (find-database "/template1/dent")
876 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
877 (find-database "www.pmsf.de/template1/dent" nil)
880 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
884 <title>Side Effects</title>
888 <title>Affected by</title>
892 <title>Exceptional Situations</title>
893 <para>If the value of <parameter>connection-spec</parameter>
894 is not a valid connection specification for the given
895 database type, an error of type
896 <errortype>clsql-invalid-spec-error</errortype> might be
900 <title>See Also</title>
903 <member><link linkend="connect"><function>connect</function></link></member>
909 <para><function>database-name-from-spec</function> is a
910 &clsql; extension.</para>
914 <refentry id="database-type">
916 <refentrytitle>DATABASE-TYPE</refentrytitle>
919 <refname>DATABASE-TYPE</refname>
920 <refpurpose>Get the type of a database object.</refpurpose>
921 <refclass>Generic Function</refclass>
924 <title>Syntax</title>
926 <function>database-type</function> <replaceable>DATABASE</replaceable> => <returnvalue>type</returnvalue></synopsis>
929 <title>Arguments and Values</title>
932 <term><parameter>database</parameter></term>
934 <para>A database object, either of type
935 <type>database</type> or of type
936 <type>closed-database</type>.</para>
940 <term><returnvalue>type</returnvalue></term>
942 <para>A keyword symbol denoting a known database back-end.</para>
948 <title>Description</title>
950 Returns the type of <parameter>database</parameter>.
954 <title>Examples</title>
956 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
957 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
958 (database-type *default-database*)
963 <title>Side Effects</title>
969 <title>Affected by</title>
975 <title>Exceptional Situations</title>
976 <para>Will signal an error if the object passed as the
977 <parameter>database</parameter> parameter is neither of type
978 <type>database</type> nor of type
979 <type>closed-database</type>.</para>
982 <title>See Also</title>
986 linkend="connect"><function>connect</function></link></member>
988 linkend="find-database"><function>find-database</function></link></member>
989 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
990 <member><link linkend="disconnect"><function>disconnect</function></link></member>
991 <member><link linkend="status"><function>status</function></link></member>
998 <function>database-type</function> is a &clsql; extension.
1003 <refentry id="disconnect">
1005 <refentrytitle>DISCONNECT</refentrytitle>
1008 <refname>DISCONNECT</refname>
1009 <refpurpose>close a database connection</refpurpose>
1010 <refclass>Function</refclass>
1013 <title>Syntax</title>
1014 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>error</replaceable> => <returnvalue>result</returnvalue></synopsis>
1017 <title>Arguments and Values</title>
1020 <term><parameter>error</parameter></term>
1022 <para>A boolean flag indicating whether to signal an error
1023 if <parameter>database</parameter> is non-&nil; but cannot
1029 <term><parameter>database</parameter></term>
1031 <para>The database to disconnect, which defaults to the
1032 database indicated by
1033 <symbol>*default-database*</symbol>.</para>
1037 <term><parameter>result</parameter></term>
1039 <para>A Boolean indicating whether a connection was
1040 successfully disconnected.
1047 <title>Description</title>
1048 <para>This function takes a <type>database</type> object as
1049 returned by <function>connect</function>, and closes the
1050 connection. If no matching database is found and
1051 <parameter>error</parameter> and
1052 <parameter>database</parameter> are both non-&nil; an error is
1053 signaled, otherwise &nil; is returned. If the database is from a
1054 pool it will be released to this pool.
1057 <para>The status of the object passed is changed to closed
1058 after the disconnection succeeds, thereby preventing further
1059 use of the object as an argument to &clsql; functions, with
1060 the exception of <function>database-name</function> and
1061 <function>database-type</function>. If the user does pass a
1062 closed database to any other &clsql; function, an error of
1063 type <errortype>sql-fatal-error</errortype> is
1067 <title>Examples</title>
1069 (disconnect :database (find-database "dent/newesim/dent"))
1074 <title>Side Effects</title>
1075 <para>The database connection is closed, and the database
1076 object is removed from the list of connected databases as
1077 returned by <function>connected-databases</function>.</para>
1078 <para>The state of the database object is changed to
1079 <type>closed</type>.</para>
1080 <para>If the database object passed is the same under
1081 <function>eq</function> as the value of
1082 <symbol>*default-database*</symbol>, then
1083 <symbol>*default-database*</symbol> is set to the first
1084 remaining database from
1085 <function>connected-databases</function> or to &nil; if no
1086 further active database exists.</para>
1089 <title>Affected by</title>
1092 <member><symbol>*default-database*</symbol></member>
1097 <title>Exceptional Situations</title>
1098 <para>If during the disconnection attempt an error is detected
1099 (e.g. because of network trouble or any other cause), an error
1100 of type <errortype>sql-error</errortype> might be
1104 <title>See Also</title>
1107 <member><link linkend="connect"><function>connect</function></link></member>
1108 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1113 <title>Notes</title>
1118 <refentry id="disconnect-pooled">
1120 <refentrytitle>DISCONNECT-POOLED</refentrytitle>
1123 <refname>DISCONNECT-POOLED</refname>
1124 <refpurpose>closes all pooled database connections</refpurpose>
1125 <refclass>Function</refclass>
1128 <title>Syntax</title>
1129 <synopsis><function>disconnect-pooled</function> => <returnvalue>t</returnvalue></synopsis>
1132 <title>Description</title>
1133 <para>This function disconnects all database connections
1134 that have been placed into the pool by calling <link
1135 linkend="connect"><function>connect</function></link> with
1140 <title>Examples</title>
1147 <title>Side Effects</title>
1148 <para>Database connections will be closed and entries in the pool are removed.
1152 <title>Affected by</title>
1155 <member><function>disconnect</function></member>
1160 <title>Exceptional Situations</title>
1161 <para>If during the disconnection attempt an error is
1162 detected (e.g. because of network trouble or any other
1163 cause), an error of type <errortype>clsql-error</errortype>
1164 might be signalled.</para>
1167 <title>See Also</title>
1170 <member><link linkend="connect"><function>connect</function></link></member>
1171 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1176 <title>Notes</title>
1177 <para><function>disconnect-pooled</function> is a &clsql;
1182 <refentry id="find-database">
1184 <refentrytitle>FIND-DATABASE</refentrytitle>
1187 <refname>FIND-DATABASE</refname>
1188 <refpurpose>>Locate a database object through it's
1190 <refclass>Function</refclass>
1193 <title>Syntax</title>
1194 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1197 <title>Arguments and Values</title>
1200 <term><parameter>database</parameter></term>
1202 <para>A database object or a string, denoting a database
1207 <term><parameter>errorp</parameter></term>
1209 <para>A generalized boolean. Defaults to
1210 <symbol>t</symbol>.</para>
1214 <term><parameter>db-type</parameter></term>
1217 A keyword symbol denoting a known database back-end.
1222 <term><returnvalue>result</returnvalue></term>
1224 <para>Either a database object, or, if
1225 <parameter>errorp</parameter> is &nil;,
1226 possibly &nil;.</para>
1232 <title>Description</title>
1233 <para><function>find-database</function> locates an active
1234 database object given the specification in
1235 <parameter>database</parameter>. If
1236 <parameter>database</parameter> is an object of type
1237 <type>database</type>, <function>find-database</function>
1238 returns this. Otherwise it will search the active databases
1239 as indicated by the list returned by
1240 <function>connected-databases</function> for a database of
1241 type <parameter>db-type</parameter> whose name (as returned by
1242 <function>database-name</function> is equal as per
1243 <function>string=</function> to the string passed as
1244 <parameter>database</parameter>. If it succeeds, it returns
1245 the first database found.</para>
1247 If <parameter>db-type</parameter> is &nil; all databases
1248 matching the string <parameter>database</parameter> are
1249 considered. If no matching databases are found and
1250 <parameter>errorp</parameter> is &nil; then &nil; is
1251 returned. If <parameter>errorp</parameter> is &nil; and one or
1252 more matching databases are found, then the most recently
1253 connected database is returned as a first value and the
1254 number of matching databases is returned as a second
1255 value. If no, or more than one, matching databases are found
1256 and <parameter>errorp</parameter> is true, an error is
1261 <title>Examples</title>
1263 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1264 => "dent/newesim/dent"
1265 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1266 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1267 (database-name *default-database*)
1268 => "dent/newesim/dent"
1270 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1271 => "/template1/dent"
1272 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1273 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1274 (database-name *default-database*)
1275 => "/template1/dent"
1277 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1278 => "www.pmsf.de/template1/dent"
1280 (find-database "dent/newesim/dent")
1281 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1282 (find-database "/template1/dent")
1283 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1284 (find-database "www.pmsf.de/template1/dent" nil)
1287 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1291 <title>Side Effects</title>
1295 <title>Affected By</title>
1298 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1303 <title>Exceptional Situations</title>
1304 <para>Will signal an error of type
1305 <errortype>clsql-error</errortype> if no matching database
1306 can be found, and <parameter>errorp</parameter> is true.
1307 Will signal an error if the value of
1308 <parameter>database</parameter> is neither an object of type
1309 <type>database</type> nor a string.</para>
1312 <title>See Also</title>
1316 linkend="database-name"><function>database-name</function></link></member>
1318 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1319 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1320 <member><link linkend="connect"><function>connect</function></link></member>
1321 <member><link linkend="status"><function>status</function></link></member>
1322 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1327 <title>Notes</title>
1328 <para>The <parameter>db-type</parameter> keyword argument to
1329 <function>find-database</function> is a &clsql;
1334 <refentry id="initialize-database-type">
1336 <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
1339 <refname>INITIALIZE-DATABASE-TYPE</refname>
1340 <refpurpose>Initializes a database type</refpurpose>
1341 <refclass>Function</refclass>
1344 <title>Syntax</title>
1346 <function>initialize-database-type &key database-type</function> => <returnvalue>result</returnvalue></synopsis>
1349 <title>Arguments and Values</title>
1352 <term><parameter>database-type</parameter></term>
1354 <para>The database type to initialize, i.e. a keyword
1355 symbol denoting a known database back-end. Defaults to
1357 <symbol>*default-database-type*</symbol>.</para>
1361 <term><returnvalue>result</returnvalue></term>
1363 <para>Either &nil; if the initialization
1364 attempt fails, or <symbol>t</symbol> otherwise.</para>
1370 <title>Description</title>
1371 <para>If the back-end specified by
1372 <parameter>database-type</parameter> has not already been
1373 initialized, as seen from
1374 <symbol>*initialized-database-types*</symbol>, an attempt is
1375 made to initialize the database. If this attempt succeeds,
1376 or the back-end has already been initialized, the function
1377 returns t, and places the keyword denoting the database type
1378 onto the list stored in
1379 <symbol>*initialized-database-types*</symbol>, if not
1380 already present.</para>
1381 <para>If initialization fails, the function returns
1382 &nil;, and/or signals an error of type
1383 <errortype>clsql-error</errortype>. The kind of action
1384 taken depends on the back-end and the cause of the
1388 <title>Examples</title>
1390 *initialized-database-types*
1392 (setf *default-database-type* :mysql)
1394 (initialize-database-type)
1395 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
1396 >> Compiling Top-Level Form:
1399 *initialized-database-types*
1401 (initialize-database-type)
1403 *initialized-database-types*
1408 <title>Side Effects</title>
1409 <para>The database back-end corresponding to the database type
1410 specified is initialized, unless it has already been
1411 initialized. This can involve any number of other side
1412 effects, as determined by the back-end implementation (like
1413 e.g. loading of foreign code, calling of foreign code,
1414 networking operations, etc.). If initialization is
1415 attempted and succeeds, the
1416 <parameter>database-type</parameter> is pushed onto the list
1418 <symbol>*initialized-database-types*</symbol>.</para>
1421 <title>Affected by</title>
1424 <member><symbol>*default-database-type*</symbol></member>
1425 <member><symbol>*initialized-database-types*</symbol></member>
1430 <title>Exceptional Situations</title>
1431 <para>If an error is encountered during the initialization
1432 attempt, the back-end may signal errors of kind
1433 <errortype>clsql-error</errortype>.</para>
1436 <title>See Also</title>
1438 <member><link linkend="initialized-database-types"><function>*initialized-database-types*</function></link></member>
1439 <member><link linkend="default-database-type"><function>*default-database-type*</function></link></member>
1443 <title>Notes</title>
1448 <refentry id="reconnect">
1450 <refentrytitle>RECONNECT</refentrytitle>
1453 <refname>RECONNECT</refname>
1454 <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
1455 <refclass>Function</refclass>
1458 <title>Syntax</title>
1460 <function>reconnect</function> &key <parameter>database</parameter> <parameter>error</parameter> <parameter>force</parameter> => <returnvalue>result</returnvalue></synopsis>
1463 <title>Arguments and Values</title>
1466 <term><parameter>database</parameter></term>
1468 <para>The database to reconnect, which defaults to the
1469 database indicated by
1470 <symbol>*default-database*</symbol>.</para>
1474 <term><parameter>error</parameter></term>
1476 <para>A boolean flag indicating whether to signal an error
1477 if <parameter>database</parameter> is non-nil but cannot
1478 be found. The default value is &nil;.
1483 <term><parameter>force</parameter></term>
1485 <para>A Boolean indicating whether to signal an error if the
1486 database connection has been lost. The default value is &t;.
1491 <term><parameter>result</parameter></term>
1493 <para>A Boolean indicating whether the database was
1494 successfully reconnected.
1501 <title>Description</title>
1502 <para>Reconnects <parameter>database</parameter> which defaults
1503 to <symbol>*default-database*</symbol> to the underlying
1504 database management system. On success, &t; is returned and the
1505 variable <symbol>*default-database*</symbol> is set to the newly
1506 reconnected database. If <parameter>database</parameter> is a
1507 database instance, this object is closed. If
1508 <parameter>database</parameter> is a string, then a connected
1509 database whose name matches <parameter>database</parameter> is
1510 sought in the list of connected databases. If no matching
1511 database is found and <parameter>error</parameter> and
1512 <parameter>database</parameter> are both non-&nil; an error is
1513 signaled, otherwise &nil; is returned.</para>
1515 <para> When the current database connection has been lost, if
1516 <parameter>force</parameter> is non-&nil; as it is by default, the
1517 connection is closed and errors are suppressed. If
1518 <parameter>force</parameter> is &nil; and the database connection
1519 cannot be closed, an error is signalled.
1523 <title>Examples</title>
1526 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}>
1528 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}>
1532 <title>Side Effects</title>
1533 <para>A database connection is re-established and
1534 <symbol>*default-database*</symbol> may be rebound to the supplied
1535 database object.</para>
1538 <title>Affected by</title>
1541 <member><symbol>*default-database*</symbol></member>
1546 <title>Exceptional Situations</title>
1548 An error may be signalled if the specified database cannot be
1549 located or if the database cannot be closed.
1553 <title>See Also</title>
1557 linkend="connect"><function>connect</function></link></member>
1559 linkend="disconnect"><function>disconnect</function></link></member>
1561 linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1566 <title>Notes</title>
1573 <refentry id="status">
1575 <refentrytitle>STATUS</refentrytitle>
1578 <refname>STATUS</refname>
1579 <refpurpose>Print information about connected databases.</refpurpose>
1580 <refclass>Function</refclass>
1583 <title>Syntax</title>
1585 <function>status</function> &optional <parameter>full</parameter> => <returnvalue></returnvalue></synopsis>
1588 <title>Arguments and Values</title>
1591 <term><parameter>full</parameter></term>
1593 <para>A boolean indicating whether to print additional
1594 table information. The default value is &nil;.
1601 <title>Description</title>
1602 <para>Prints information about the currently connected databases
1603 to <symbol>*STANDARD-OUTPUT*</symbol>. The argument
1604 <parameter>full</parameter> is &nil; by default and a value of t
1605 means that more detailed information about each database is
1610 <title>Examples</title>
1614 CLSQL STATUS: 2004-06-13 15:07:39
1615 --------------------------------------------------------
1616 DATABASE TYPE RECORDING
1617 --------------------------------------------------------
1618 localhost/test/petrov mysql nil
1619 localhost/test/petrov postgresql nil
1620 localhost/test/petrov postgresql-socket nil
1621 test/petrov odbc nil
1622 * :memory: sqlite nil
1623 --------------------------------------------------------
1627 CLSQL STATUS: 2004-06-13 15:08:08
1628 -------------------------------------------------------------------------------
1629 DATABASE TYPE RECORDING POOLED TABLES VIEWS
1630 -------------------------------------------------------------------------------
1631 localhost/test/petrov mysql nil nil 7 0
1632 localhost/test/petrov postgresql nil nil 7 0
1633 localhost/test/petrov postgresql-socket nil nil 7 0
1634 test/petrov odbc nil nil 7 0
1635 * :memory: sqlite nil nil 0 0
1636 -------------------------------------------------------------------------------
1640 <title>Side Effects</title>
1646 <title>Affected by</title>
1652 <title>Exceptional Situations</title>
1658 <title>See Also</title>
1661 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1662 <member><link linkend="connect"><function>connect</function></link></member>
1663 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1664 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
1665 <member><link linkend="find-database"><function>find-database</function></link></member>
1670 <title>Notes</title>
1678 <!-- create/probe/list/destroytruncate-database -->
1680 <refentry id="create-database">
1682 <refentrytitle>CREATE-DATABASE</refentrytitle>
1685 <refname>CREATE-DATABASE</refname>
1686 <refpurpose>create a database</refpurpose>
1687 <refclass>Function</refclass>
1690 <title>Syntax</title>
1691 <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1694 <title>Arguments and Values</title>
1697 <term><parameter>connection-spec</parameter></term>
1699 <para>A connection specification</para>
1703 <term><parameter>database-type</parameter></term>
1705 <para>A database type specifier, i.e. a keyword.
1706 This defaults to the value of
1707 <symbol>*default-database-type*</symbol></para>
1711 <term><parameter>success</parameter></term>
1713 <para>A boolean flag. If &t;, a new database was
1714 successfully created.
1721 <title>Description</title>
1722 <para>This function creates a database in the database system
1723 specified by <parameter>database-type</parameter>.
1727 <title>Examples</title>
1729 (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
1732 (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
1734 Error: While trying to access database localhost/new/dent
1735 using database-type MYSQL:
1736 Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1737 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1739 [condition type: CLSQL-ACCESS-ERROR]
1743 <title>Side Effects</title>
1744 <para>A database will be created on the filesystem of the host.</para>
1747 <title>Exceptional Situations</title>
1748 <para>An exception will be thrown if the database system does
1749 not allow new databases to be created or if database creation
1753 <title>See Also</title>
1756 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1757 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1758 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1763 <title>Notes</title>
1764 <para>This function may invoke the operating systems
1765 functions. Thus, some database systems may require the
1766 administration functions to be available in the current
1767 <symbol>PATH</symbol>. At this time, the
1768 <symbol>:mysql</symbol> backend requires
1769 <filename>mysqladmin</filename> and the
1770 <symbol>:postgresql</symbol> backend requires
1771 <filename>createdb</filename>.</para>
1773 <function>create-database</function> is a &clsql; extension.
1778 <refentry id="destroy-database">
1780 <refentrytitle>DESTROY-DATABASE</refentrytitle>
1783 <refname>DESTROY-DATABASE</refname>
1784 <refpurpose>destroys a database</refpurpose>
1785 <refclass>Function</refclass>
1788 <title>Syntax</title>
1789 <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1792 <title>Arguments and Values</title>
1795 <term><parameter>connection-spec</parameter></term>
1797 <para>A connection specification</para>
1801 <term><parameter>database-type</parameter></term>
1803 <para>A database type specifier, i.e. a keyword.
1804 This defaults to the value of
1805 <symbol>*default-database-type*</symbol></para>
1809 <term><parameter>success</parameter></term>
1811 <para>A boolean flag. If &t;, the database was
1812 successfully destroyed.
1819 <title>Description</title>
1820 <para>This function destroys a database in the database system
1821 specified by <parameter>database-type</parameter>.
1825 <title>Examples</title>
1827 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1830 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1832 Error: While trying to access database localhost/test2/root
1833 using database-type POSTGRESQL:
1834 Error database-destroy failed: dropdb: database removal failed: ERROR: database "test2" does not exist
1836 [condition type: CLSQL-ACCESS-ERROR]
1840 <title>Side Effects</title>
1841 <para>A database will be removed from the filesystem of the host.</para>
1844 <title>Exceptional Situations</title>
1845 <para>An exception will be thrown if the database system does not
1846 allow databases to be removed, the database does not exist, or
1847 if database removal fails.</para>
1850 <title>See Also</title>
1853 <member><link linkend="create-database"><function>create-database</function></link></member>
1854 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1855 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1860 <title>Notes</title>
1861 <para>This function may invoke the operating systems
1862 functions. Thus, some database systems may require the
1863 administration functions to be available in the current
1864 <symbol>PATH</symbol>. At this time, the
1865 <symbol>:mysql</symbol> backend requires
1866 <filename>mysqladmin</filename> and the
1867 <symbol>:postgresql</symbol> backend requires
1868 <filename>dropdb</filename>.</para>
1870 <function>destroy-database</function> is a &clsql; extension.
1875 <refentry id="probe-database">
1877 <refentrytitle>PROBE-DATABASE</refentrytitle>
1880 <refname>PROBE-DATABASE</refname>
1881 <refpurpose>tests for existence of a database</refpurpose>
1882 <refclass>Function</refclass>
1885 <title>Syntax</title>
1886 <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1889 <title>Arguments and Values</title>
1892 <term><parameter>connection-spec</parameter></term>
1894 <para>A connection specification</para>
1898 <term><parameter>database-type</parameter></term>
1900 <para>A database type specifier, i.e. a keyword.
1901 This defaults to the value of
1902 <symbol>*default-database-type*</symbol></para>
1906 <term><parameter>success</parameter></term>
1908 <para>A boolean flag. If &t;, the database exists
1909 in the database system.
1916 <title>Description</title>
1917 <para>This function tests for the existence of a database in
1918 the database system specified by
1919 <parameter>database-type</parameter>.
1923 <title>Examples</title>
1925 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1930 <title>Side Effects</title>
1934 <title>Exceptional Situations</title>
1935 <para>An exception maybe thrown if the database system does
1936 not receive administrator-level authentication since function
1937 may need to read the administrative database of the database
1941 <title>See Also</title>
1944 <member><link linkend="create-database"><function>create-database</function></link></member>
1945 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1946 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1951 <title>Notes</title>
1953 <function>probe-database</function> is a &clsql; extension.
1958 <refentry id="list-databases">
1960 <refentrytitle>LIST-DATABASES</refentrytitle>
1963 <refname>LIST-DATABASES</refname>
1964 <refpurpose>List databases matching the supplied connection spec
1965 and database type.</refpurpose>
1966 <refclass>Function</refclass>
1969 <title>Syntax</title>
1971 <function>list-databases</function> <parameter>connection-spec</parameter> &key <parameter>database-type</parameter> => <returnvalue>result</returnvalue></synopsis>
1974 <title>Arguments and Values</title>
1977 <term><parameter>connection-spec</parameter></term>
1979 <para>A connection specification</para>
1983 <term><parameter>database-type</parameter></term>
1985 <para>A database type specifier, i.e. a keyword.
1986 This defaults to the value of
1987 <symbol>*default-database-type*</symbol></para>
1991 <term><parameter>result</parameter></term>
1993 <para>A list of matching databases.
2000 <title>Description</title>
2002 This function returns a list of databases existing in the
2003 database system specified by
2004 <parameter>database-type</parameter>.
2008 <title>Examples</title>
2010 (list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql)
2011 => ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test")
2015 <title>Side Effects</title>
2021 <title>Affected by</title>
2027 <title>Exceptional Situations</title>
2029 An exception maybe thrown if the database system does not
2030 receive administrator-level authentication since function may
2031 need to read the administrative database of the database
2036 <title>See Also</title>
2039 <member><link linkend="create-database"><function>create-database</function></link></member>
2040 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2041 <member><link linkend="probe-database"><function>probe-database</function></link></member>
2046 <title>Notes</title>
2048 <function>list-databases</function> is a &clsql; extension.
2054 <!-- with-database and with-default-database -->
2056 <refentry id="with-database">
2058 <refentrytitle>WITH-DATABASE</refentrytitle>
2061 <refname>WITH-DATABASE</refname>
2062 <refpurpose>Execute a body of code with a variable bound to a
2063 specified database object.</refpurpose>
2064 <refclass>Macro</refclass>
2067 <title>Syntax</title>
2069 <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>
2072 <title>Arguments and Values</title>
2075 <term><parameter>db-var</parameter></term>
2077 <para>A variable which is bound to the specified database.
2082 <term><parameter>connection-spec</parameter></term>
2084 <para>A vendor specific connection specification supplied
2085 as a list or as a string.</para>
2089 <term><parameter>connect-args</parameter></term>
2091 <para>Other optional arguments to
2092 <function>connect</function>. This macro use a value of
2093 &nil; for <function>connect</function>'s
2094 <replaceable>make-default</replaceable> key, This is in
2095 contrast to to the connect function which has a default
2096 value of &t; for <replaceable>make-default</replaceable>.
2101 <term><parameter>body</parameter></term>
2103 <para>A Lisp code body.
2108 <term><parameter>result</parameter></term>
2110 <para>Determined by the result of executing the last
2111 expression in <parameter>body</parameter>.
2118 <title>Description</title>
2119 <para>Evaluate <parameter>body</parameter> in an environment,
2120 where <parameter>db-var</parameter> is bound to the database
2121 connection given by <parameter>connection-spec</parameter> and
2122 <parameter>connect-args</parameter>. The connection is
2123 automatically closed or released to the pool on exit from the
2128 <title>Examples</title>
2130 (connected-databases)
2132 (with-database (db '(":memory:") :database-type :sqlite
2136 (connected-databases)
2141 <title>Side Effects</title>
2143 See <function>connect</function> and <function>disconnect</function>.
2147 <title>Affected by</title>
2149 See <function>connect</function> and <function>disconnect</function>.
2153 <title>Exceptional Situations</title>
2155 See <function>connect</function> and <function>disconnect</function>.
2159 <title>See Also</title>
2162 <member><link linkend="connect"><function>connect</function></link></member>
2163 <member><link linkend="disconnect"><function>disconnect</function></link></member>
2164 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
2165 <member><link linkend="with-default-database"><function>with-default-database</function></link></member>
2170 <title>Notes</title>
2172 <function>with-database</function> is a &clsql; extension.
2177 <refentry id="with-default-database">
2179 <refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
2182 <refname>WITH-DEFAULT-DATABASE</refname>
2183 <refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
2184 <refclass>Macro</refclass>
2187 <title>Syntax</title>
2189 <function>with-default-database</function> <replaceable>database</replaceable> &rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
2192 <title>Arguments and Values</title>
2195 <term><parameter>database</parameter></term>
2197 <para>An active database object.
2202 <term><parameter>body</parameter></term>
2204 <para>A Lisp code body.
2209 <term><parameter>result</parameter></term>
2211 <para>Determined by the result of executing the last
2212 expression in <parameter>body</parameter>.
2219 <title>Description</title>
2220 <para>Perform <parameter>body</parameter> with
2221 <parameter>DATABASE</parameter> bound as
2222 <symbol>*default-database*</symbol>.
2226 <title>Examples</title>
2229 => #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}>
2231 (let ((database (clsql:find-database ":memory:")))
2232 (with-default-database (database)
2233 (database-name *default-database*)))
2238 <title>Side Effects</title>
2244 <title>Affected by</title>
2250 <title>Exceptional Situations</title>
2252 Calls to &clsql; functions in <parameter>body</parameter> may signal
2253 errors if <parameter>database</parameter> is not an active database
2258 <title>See Also</title>
2261 <member><link linkend="with-database"><function>with-database</function></link></member>
2262 <member><link linkend="default-database"><symbol>*default-database*</symbol></link></member>
2267 <title>Notes</title>
2269 <function>with-default-database</function> is a &clsql; extension.