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>
128 <refentry id="db-pool-max-free-connections">
130 <refentrytitle>*DB-POOL-MAX-FREE-CONNECTIONS*</refentrytitle>
133 <refname>*DB-POOL-MAX-FREE-CONNECTIONS*</refname>
134 <refpurpose>How many free connections should the connection pool try to keep.</refpurpose>
135 <refclass>Parameter</refclass>
138 <title>Value Type</title>
142 <title>Initial Value</title>
146 <title>Description</title>
147 <para>Threshold of free-connections in the pool before we disconnect a
148 database rather than returning it to the pool. This is really a heuristic
149 that should, on avg keep the free connections about this size.</para>
151 <para>This is not a hard limit, the number of connections in
152 the pool may exceed this value.</para>
156 <title>Examples</title>
158 (setf clsql-sys:*db-pool-max-free-connections* 2)
162 <title>Affected By</title>
166 <title>See Also</title>
169 <member><link linkend="connect"><function>connect</function></link></member>
170 <member><link linkend="disconnect"><function>disconnect</function></link></member>
183 <refentry id="default-database">
185 <refentrytitle>*DEFAULT-DATABASE*</refentrytitle>
188 <refname>*DEFAULT-DATABASE*</refname>
189 <refpurpose>The default database object to use.</refpurpose>
190 <refclass>Variable</refclass>
193 <title>Value Type</title>
194 <para>Any object of type <type>database</type>, or &nil; to
195 indicate no default database.</para>
198 <title>Initial Value</title>
202 <title>Description</title>
203 <para>Any function or macro in &clsql; that operates on a
204 database uses the value of this variable as the default value
205 for it's <parameter>database</parameter> parameter.</para>
206 <para>The value of this parameter is changed by calls to
207 <function>connect</function>, which sets
208 <symbol>*default-database*</symbol> to the database object
209 it returns. It is also changed by calls to
210 <function>disconnect</function>, when the database object
211 being disconnected is the same as the value of
212 <symbol>*default-database*</symbol>. In this case
213 <function>disconnect</function> sets
214 <symbol>*default-database*</symbol> to the first database
215 that remains in the list of active databases as returned by
216 <function>connected-databases</function>, or
217 &nil; if no further active databases
219 <para>The user may change <symbol>*default-database*</symbol>
220 at any time to a valid value of his choice.</para>
222 <para>If the value of <symbol>*default-database*</symbol> is
223 &nil;, then all calls to &clsql; functions on
224 databases must provide a suitable
225 <parameter>database</parameter> parameter, or an error will be
230 <title>Examples</title>
232 (connected-databases)
234 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
235 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
236 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
237 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
238 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
239 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
241 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
245 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
249 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
254 (connected-databases)
259 <title>Affected By</title>
261 <member><link linkend="connect"><function>connect</function></link></member>
262 <member><link linkend="disconnect"><function>disconnect</function></link></member>
266 <title>See Also</title>
269 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
276 <para>This variable is intended to facilitate working with
277 &clsql; in an interactive
278 fashion at the top-level loop, and because of this,
279 <function>connect</function> and
280 <function>disconnect</function> provide some fairly
281 complex behaviour to keep
282 <symbol>*default-database*</symbol> set to useful values.
283 Programmatic use of &clsql;
284 should never depend on the value of
285 <symbol>*default-database*</symbol> and should provide
286 correct database objects via the
287 <parameter>database</parameter> parameter to functions
293 <refentry id="default-database-type">
295 <refentrytitle>*DEFAULT-DATABASE-TYPE*</refentrytitle>
298 <refname>*DEFAULT-DATABASE-TYPE*</refname>
299 <refpurpose>The default database type to use</refpurpose>
300 <refclass>Variable</refclass>
303 <title>Value Type</title>
304 <para>Any keyword representing a valid database back-end of
305 &clsql;, or &nil;.</para>
308 <title>Initial Value</title>
312 <title>Description</title>
313 <para>The value of this variable is used in calls to
314 <function>initialize-database-type</function> and
315 <function>connect</function> as the default value of the
316 <parameter>database-type</parameter> parameter.</para>
318 <para>If the value of this variable is &nil;,
320 <function>initialize-database-type</function> or
321 <function>connect</function> will have to specify the
322 <parameter>database-type</parameter> to use, or a
323 general-purpose error will be signalled.</para>
327 <title>Examples</title>
329 (setf *default-database-type* :mysql)
331 (initialize-database-type)
336 <title>Affected By</title>
340 <title>See Also</title>
343 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
352 <refentry id="initialized-database-types">
354 <refentrytitle>*INITIALIZED-DATABASE-TYPES*</refentrytitle>
357 <refname>*INITIALIZED-DATABASE-TYPES*</refname>
358 <refpurpose>List of all initialized database types</refpurpose>
359 <refclass>Variable</refclass>
362 <title>Value Type</title>
363 <para>A list of all initialized database types, each of which
364 represented by it's corresponding keyword.</para>
367 <title>Initial Value</title>
371 <title>Description</title>
372 <para>This variable is updated whenever
373 <function>initialize-database-type</function> is called for a
374 database type which hasn't already been initialized before, as
375 determined by this variable. In that case the keyword
376 representing the database type is pushed onto the list stored in
377 <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
379 <para>Attempts to modify the value of this variable will
380 result in undefined behaviour.</para>
384 <title>Examples</title>
386 (setf *default-database-type* :mysql)
388 (initialize-database-type)
390 *initialized-database-types*
395 <title>Affected By</title>
398 <member><function>initialize-database-type</function></member>
403 <title>See Also</title>
406 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
411 <para>Direct access to this variable is primarily provided
412 because of compatibility with Harlequin's <application>Common
413 SQL</application>.</para>
417 <refentry id="connect">
419 <refentrytitle>CONNECT</refentrytitle>
422 <refname>CONNECT</refname>
423 <refpurpose>create a connection to a database.</refpurpose>
424 <refclass>Function</refclass>
427 <title>Syntax</title>
428 <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>
431 <title>Arguments and Values</title>
434 <term><parameter>connection-spec</parameter></term>
436 <para>A SQL backend specific connection specification
437 supplied as a list or as a string.</para>
438 <para>For the MySQL backend, this list includes an
439 optional associative list of connection options. The
440 options list is parsed and supplied to the MySQL API
441 using <function>mysql_options</function> in between the
442 calls to <function>mysql_init</function>
443 and <function>mysql_real_connect</function>.</para>
447 <term><parameter>if-exists</parameter></term>
449 <para>This indicates the action to take if a connection
450 to the same database exists already. See below for the
451 legal values and actions. It defaults to the value of
452 <symbol>*connect-if-exists*</symbol>.</para>
456 <term><parameter>database-type</parameter></term>
458 <para>A database type specifier, i.e. a keyword.
459 This defaults to the value of
460 <symbol>*default-database-type*</symbol></para>
464 <term><parameter>pool</parameter></term>
466 <para>A boolean flag. If &t;, acquire connection from a
467 pool of open connections. If the pool is empty, a new
468 connection is created. The default is &nil;.
473 <term><parameter>make-default</parameter></term>
475 <para>A boolean flag. If &t;,
476 <symbol>*default-database*</symbol> is set to the new
477 connection, otherwise <symbol>*default-database*</symbol>
478 is not changed. The default is &t;.
483 <term><returnvalue>database</returnvalue></term>
485 <para>The database object representing the connection.</para>
491 <title>Description</title>
492 <para>This function takes a connection specification and
493 a database type and creates a connection to the database
494 specified by those. The type and structure of the
495 connection specification depend on the database type.</para>
496 <para>The parameter <parameter>if-exists</parameter> specifies
497 what to do if a connection to the database specified exists
498 already, which is checked by calling
499 <function>find-database</function> on the database name
500 returned by <function>database-name-from-spec</function>
501 when called with the <parameter>connection-spec</parameter>
502 and <parameter>database-type</parameter> parameters. The
503 possible values of <parameter>if-exists</parameter> are:
506 <term><symbol>:new</symbol></term>
508 <para>Go ahead and create a new connection.</para>
512 <term><symbol>:warn-new</symbol></term>
514 <para>This is just like <symbol>:new</symbol>, but
515 also signals a warning of type
516 <errortype>clsql-exists-warning</errortype>,
517 indicating the old and newly created
522 <term><symbol>:error</symbol></term>
524 <para>This will cause <function>connect</function> to
525 signal a correctable error of type
526 <errortype>clsql-exists-error</errortype>. The
527 user may choose to proceed, either by indicating
528 that a new connection shall be created, via the
529 restart <symbol>create-new</symbol>, or by
530 indicating that the existing connection shall be
531 used, via the restart
532 <symbol>use-old</symbol>.</para>
536 <term><symbol>:old</symbol></term>
538 <para>This will cause <function>connect</function> to
539 use an old connection if one exists.</para>
543 <term><symbol>:warn-old</symbol></term>
545 <para>This is just like <symbol>:old</symbol>, but
546 also signals a warning of type
547 <errortype>clsql-exists-warning</errortype>,
548 indicating the old database used, via the slots
549 <symbol>old-db</symbol> and
550 <symbol>new-db</symbol></para>
555 <para>The database name of the returned database object will
556 be the same under <function>string=</function> as that which
557 would be returned by a call to
558 <function>database-name-from-spec</function> with the given
559 <parameter>connection-spec</parameter> and
560 <parameter>database-type</parameter> parameters.</para>
563 <title>Examples</title>
565 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
566 => "dent/newesim/dent"
567 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
568 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
570 => "dent/newesim/dent"
572 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
573 >> In call to CONNECT:
574 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
577 >> 0: [CREATE-NEW] Create a new connection.
578 >> 1: [USE-OLD ] Use the existing connection.
579 >> 2: [ABORT ] Return to Top-Level.
581 >> Debug (type H for help)
583 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
585 >> ; File: /prj/CLSQL/sql/sql.cl
586 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
587 >> (CREATE-NEW NIL :REPORT "Create a new connection."
589 >> (USE-OLD NIL :REPORT "Use the existing connection."
590 >> (SETQ RESULT OLD-DB)))
592 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
596 <title>Side Effects</title>
597 <para>A database connection is established, and the resultant
598 database object is registered, so as to appear in the list
599 returned by <function>connected-databases</function>.
600 <symbol>*default-database*</symbol> may be rebound to the
601 created object.</para>
604 <title>Affected by</title>
608 <link linkend="default-database-type">
609 <symbol>*default-database-type*</symbol>
613 <link linkend="connect-if-exists">
614 <symbol>*connect-if-exists*</symbol>
621 <title>Exceptional Situations</title>
622 <para>If the connection specification is not syntactically or
623 semantically correct for the given database type, an error of
624 type <errortype>sql-user-error</errortype> is
625 signalled. If during the connection attempt an error is
626 detected (e.g. because of permission problems, network trouble
627 or any other cause), an error of type
628 <errortype>sql-database-error</errortype> is signalled.</para>
629 <para>If a connection to the database specified by
630 <parameter>connection-spec</parameter> exists already,
631 conditions are signalled according to the
632 <parameter>if-exists</parameter> parameter, as described
636 <title>See Also</title>
638 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
639 <member><link linkend="disconnect"><function>disconnect</function></link></member>
640 <member><link linkend="reconnect"><function>reconnect</function></link></member>
641 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
642 <member><link linkend="find-database"><function>find-database</function></link></member>
643 <member><link linkend="status"><function>status</function></link></member>
648 <para>The <parameter>pool</parameter> and
649 <parameter>make-default</parameter> keyword arguments to
650 <function>connect</function> are &clsql; extensions.</para>
654 <refentry id="connected-databases">
656 <refentrytitle>CONNECTED-DATABASES</refentrytitle>
659 <refname>CONNECTED-DATABASES</refname>
660 <refpurpose>Return the list of active database objects.</refpurpose>
661 <refclass>Function</refclass>
664 <title>Syntax</title>
666 <function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
669 <title>Arguments and Values</title>
672 <term><returnvalue>databases</returnvalue></term>
674 <para>The list of active database objects.</para>
680 <title>Description</title>
681 <para>This function returns the list of active database
682 objects, i.e. all those database objects created by calls to
683 <function>connect</function>, which have not been closed by
684 calling <function>disconnect</function> on them.</para>
686 <para>The consequences of modifying the list returned by
687 <function>connected-databases</function> are
692 <title>Examples</title>
694 (connected-databases)
696 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
697 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
698 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
699 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
700 (connected-databases)
701 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
702 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
705 (connected-databases)
706 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
709 (connected-databases)
714 <title>Side Effects</title>
718 <title>Affected By</title>
721 <member><function>connect</function></member>
722 <member><function>disconnect</function></member>
727 <title>Exceptional Situations</title>
731 <title>See Also</title>
733 <member><link linkend="disconnect"><function>disconnect</function></link></member>
734 <member><link linkend="connect"><function>connect</function></link></member>
735 <member><link linkend="status"><function>status</function></link></member>
736 <member><link linkend="find-database"><function>find-database</function></link></member>
746 <refentry id="database-name">
748 <refentrytitle>DATABASE-NAME</refentrytitle>
751 <refname>DATABASE-NAME</refname>
752 <refpurpose>Get the name of a database object</refpurpose>
753 <refclass>Generic Function</refclass>
756 <title>Syntax</title>
757 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
760 <title>Arguments and Values</title>
763 <term><parameter>database</parameter></term>
765 <para>A database object, either of type
766 <type>database</type> or of type
767 <type>closed-database</type>.</para>
771 <term><returnvalue>name</returnvalue></term>
773 <para>A string describing the identity of the database
774 to which this database object is connected to.</para>
780 <title>Description</title>
781 <para>This function returns the database name of the given
782 database. The database name is a string which somehow
783 describes the identity of the database to which this
784 database object is or has been connected. The database name
785 of a database object is determined at
786 <function>connect</function> time, when a call to
787 <function>database-name-from-spec</function> derives the
788 database name from the connection specification passed to
789 <function>connect</function> in the
790 <parameter>connection-spec</parameter> parameter.</para>
791 <para>The database name is used via
792 <function>find-database</function> in
793 <function>connect</function> to determine whether database
794 connections to the specified database exist already.</para>
795 <para>Usually the database name string will include
796 indications of the host, database name, user, or port that
797 where used during the connection attempt. The only
798 important thing is that this string shall try to identify
799 the database at the other end of the connection. Connection
800 specifications parts like passwords and credentials shall
801 not be used as part of the database name.</para>
804 <title>Examples</title>
806 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
807 => "dent/newesim/dent"
808 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
809 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
810 (database-name *default-database*)
811 => "dent/newesim/dent"
813 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
815 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
816 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
817 (database-name *default-database*)
820 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
821 => "www.pmsf.de/template1/dent"
825 <title>Side Effects</title>
829 <title>Affected By</title>
832 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
837 <title>Exceptional Situations</title>
838 <para>Will signal an error if the object passed as the
839 <parameter>database</parameter> parameter is neither of type
840 <type>database</type> nor of type
841 <type>closed-database</type>.</para>
844 <title>See Also</title>
848 linkend="connect"><function>connect</function></link></member>
850 linkend="find-database"><function>find-database</function></link></member>
851 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
852 <member><link linkend="disconnect"><function>disconnect</function></link></member>
853 <member><link linkend="status"><function>status</function></link></member>
863 <refentry id="database-name-from-spec">
865 <refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
868 <refname>DATABASE-NAME-FROM-SPEC</refname>
869 <refpurpose>Return the database name string corresponding to
870 the given connection specification.</refpurpose>
871 <refclass>Generic Function</refclass>
874 <title>Syntax</title>
876 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
879 <title>Arguments and Values</title>
882 <term><parameter>connection-spec</parameter></term>
884 <para>A connection specification, whose structure and
885 interpretation are dependent on the
886 <parameter>database-type</parameter>.</para>
890 <term><parameter>database-type</parameter></term>
892 <para>A database type specifier, i.e. a keyword.</para>
896 <term><returnvalue>name</returnvalue></term>
898 <para>A string denoting a database name.</para>
904 <title>Description</title>
905 <para>This generic function takes a connection specification
906 and a database type and returns the database name of the
907 database object that would be created had
908 <function>connect</function> been called with the given
909 connection specification and database types.</para>
910 <para>This function is useful in determining a database name
911 from the connection specification, since the way the
912 connection specification is converted into a database name
913 is dependent on the database type.</para>
916 <title>Examples</title>
918 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
919 => "dent/newesim/dent"
920 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
921 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
922 (database-name *default-database*)
923 => "dent/newesim/dent"
925 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
927 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
928 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
929 (database-name *default-database*)
932 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
933 => "www.pmsf.de/template1/dent"
935 (find-database "dent/newesim/dent")
936 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
937 (find-database "/template1/dent")
938 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
939 (find-database "www.pmsf.de/template1/dent" nil)
942 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
946 <title>Side Effects</title>
950 <title>Affected by</title>
954 <title>Exceptional Situations</title>
955 <para>If the value of <parameter>connection-spec</parameter>
956 is not a valid connection specification for the given
957 database type, an error of type
958 <errortype>clsql-invalid-spec-error</errortype> might be
962 <title>See Also</title>
965 <member><link linkend="connect"><function>connect</function></link></member>
971 <para><function>database-name-from-spec</function> is a
972 &clsql; extension.</para>
976 <refentry id="database-type">
978 <refentrytitle>DATABASE-TYPE</refentrytitle>
981 <refname>DATABASE-TYPE</refname>
982 <refpurpose>Get the type of a database object.</refpurpose>
983 <refclass>Generic Function</refclass>
986 <title>Syntax</title>
988 <function>database-type</function> <replaceable>DATABASE</replaceable> => <returnvalue>type</returnvalue></synopsis>
991 <title>Arguments and Values</title>
994 <term><parameter>database</parameter></term>
996 <para>A database object, either of type
997 <type>database</type> or of type
998 <type>closed-database</type>.</para>
1002 <term><returnvalue>type</returnvalue></term>
1004 <para>A keyword symbol denoting a known database back-end.</para>
1010 <title>Description</title>
1012 Returns the type of <parameter>database</parameter>.
1016 <title>Examples</title>
1018 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1019 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1020 (database-type *default-database*)
1025 <title>Side Effects</title>
1031 <title>Affected by</title>
1037 <title>Exceptional Situations</title>
1038 <para>Will signal an error if the object passed as the
1039 <parameter>database</parameter> parameter is neither of type
1040 <type>database</type> nor of type
1041 <type>closed-database</type>.</para>
1044 <title>See Also</title>
1048 linkend="connect"><function>connect</function></link></member>
1050 linkend="find-database"><function>find-database</function></link></member>
1051 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1052 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1053 <member><link linkend="status"><function>status</function></link></member>
1058 <title>Notes</title>
1060 <function>database-type</function> is a &clsql; extension.
1065 <refentry id="disconnect">
1067 <refentrytitle>DISCONNECT</refentrytitle>
1070 <refname>DISCONNECT</refname>
1071 <refpurpose>close a database connection</refpurpose>
1072 <refclass>Function</refclass>
1075 <title>Syntax</title>
1076 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>error</replaceable> => <returnvalue>result</returnvalue></synopsis>
1079 <title>Arguments and Values</title>
1082 <term><parameter>error</parameter></term>
1084 <para>A boolean flag indicating whether to signal an error
1085 if <parameter>database</parameter> is non-&nil; but cannot
1091 <term><parameter>database</parameter></term>
1093 <para>The database to disconnect, which defaults to the
1094 database indicated by
1095 <symbol>*default-database*</symbol>.</para>
1099 <term><parameter>result</parameter></term>
1101 <para>A Boolean indicating whether a connection was
1102 successfully disconnected.
1109 <title>Description</title>
1110 <para>This function takes a <type>database</type> object as
1111 returned by <function>connect</function>, and closes the
1112 connection. If no matching database is found and
1113 <parameter>error</parameter> and
1114 <parameter>database</parameter> are both non-&nil; an error is
1115 signaled, otherwise &nil; is returned. If the database is from a
1116 pool it will be released to this pool.
1119 <para>The status of the object passed is changed to closed
1120 after the disconnection succeeds, thereby preventing further
1121 use of the object as an argument to &clsql; functions, with
1122 the exception of <function>database-name</function> and
1123 <function>database-type</function>. If the user does pass a
1124 closed database to any other &clsql; function, an error of
1125 type <errortype>sql-fatal-error</errortype> is
1129 <title>Examples</title>
1131 (disconnect :database (find-database "dent/newesim/dent"))
1136 <title>Side Effects</title>
1137 <para>The database object is removed from the list of connected databases as
1138 returned by <link linkend="connected-databases"><function>connected-databases</function></link>.</para>
1139 <para>If the database object passed is the same under
1140 <function>eq</function> as the value of
1141 <symbol>*default-database*</symbol>, then
1142 <symbol>*default-database*</symbol> is set to the first
1143 remaining database from
1144 <function>connected-databases</function> or to &nil; if no
1145 further active database exists.</para>
1147 <title>Non-pooled</title>
1148 <para>The database connection is closed and the state of the
1149 database object is changed to <type>closed</type>.</para>
1152 <title>Pooled</title>
1153 <para>Unless there are already <link linkend="db-pool-max-free-connections">
1154 <symbol>*db-pool-max-free-connections*</symbol>
1155 </link> free connections in the pool it is returned to the
1156 pool, with the backend having an opportunity to run
1157 generic cleanup on the connection first. If the max free
1158 connections has already been reached then it is
1159 disconnected as if it were not in the pool.
1164 <title>Affected by</title>
1168 <link linkend="default-database">
1169 <symbol>*default-database*</symbol>
1173 <link linkend="db-pool-max-free-connections">
1174 <symbol>*db-pool-max-free-connections*</symbol>
1181 <title>Exceptional Situations</title>
1182 <para>If during the disconnection attempt an error is detected
1183 (e.g. because of network trouble or any other cause), an error
1184 of type <errortype>sql-error</errortype> might be
1188 <title>See Also</title>
1191 <member><link linkend="connect"><function>connect</function></link></member>
1192 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1197 <title>Notes</title>
1202 <refentry id="disconnect-pooled">
1204 <refentrytitle>DISCONNECT-POOLED</refentrytitle>
1207 <refname>DISCONNECT-POOLED</refname>
1208 <refpurpose>closes all pooled database connections</refpurpose>
1209 <refclass>Function</refclass>
1212 <title>Syntax</title>
1213 <synopsis><function>disconnect-pooled</function> &optional <symbol>clear</symbol> => <returnvalue>t</returnvalue></synopsis>
1216 <title>Description</title>
1217 <para>This function disconnects all database connections
1218 that have been placed into the pool by calling <link
1219 linkend="connect"><function>connect</function></link> with
1222 <para>If optional argument <symbol>clear</symbol> is non-&nil;
1223 then the connection-pool objects are also removed.</para>
1226 <title>Examples</title>
1233 <title>Side Effects</title>
1234 <para>Database connections will be closed and *all* entries in
1235 the pool are removed. This is done with great prejudice and no
1236 thought to thread safety or whether that connection is
1237 currently in use.</para>
1240 <title>Affected by</title>
1243 <member><function>disconnect</function></member>
1248 <title>Exceptional Situations</title>
1249 <para>If during the disconnection attempt an error is
1250 detected (e.g. because of network trouble or any other
1251 cause), an error of type <errortype>clsql-error</errortype>
1252 might be signalled.</para>
1255 <title>See Also</title>
1258 <member><link linkend="connect"><function>connect</function></link></member>
1259 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1264 <title>Notes</title>
1265 <para><function>disconnect-pooled</function> is a &clsql;
1270 <refentry id="find-database">
1272 <refentrytitle>FIND-DATABASE</refentrytitle>
1275 <refname>FIND-DATABASE</refname>
1276 <refpurpose>>Locate a database object through it's
1278 <refclass>Function</refclass>
1281 <title>Syntax</title>
1282 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1285 <title>Arguments and Values</title>
1288 <term><parameter>database</parameter></term>
1290 <para>A database object or a string, denoting a database
1295 <term><parameter>errorp</parameter></term>
1297 <para>A generalized boolean. Defaults to
1298 <symbol>t</symbol>.</para>
1302 <term><parameter>db-type</parameter></term>
1305 A keyword symbol denoting a known database back-end.
1310 <term><returnvalue>result</returnvalue></term>
1312 <para>Either a database object, or, if
1313 <parameter>errorp</parameter> is &nil;,
1314 possibly &nil;.</para>
1320 <title>Description</title>
1321 <para><function>find-database</function> locates an active
1322 database object given the specification in
1323 <parameter>database</parameter>. If
1324 <parameter>database</parameter> is an object of type
1325 <type>database</type>, <function>find-database</function>
1326 returns this. Otherwise it will search the active databases
1327 as indicated by the list returned by
1328 <function>connected-databases</function> for a database of
1329 type <parameter>db-type</parameter> whose name (as returned by
1330 <function>database-name</function> is equal as per
1331 <function>string=</function> to the string passed as
1332 <parameter>database</parameter>. If it succeeds, it returns
1333 the first database found.</para>
1335 If <parameter>db-type</parameter> is &nil; all databases
1336 matching the string <parameter>database</parameter> are
1337 considered. If no matching databases are found and
1338 <parameter>errorp</parameter> is &nil; then &nil; is
1339 returned. If <parameter>errorp</parameter> is &nil; and one or
1340 more matching databases are found, then the most recently
1341 connected database is returned as a first value and the
1342 number of matching databases is returned as a second
1343 value. If no, or more than one, matching databases are found
1344 and <parameter>errorp</parameter> is true, an error is
1349 <title>Examples</title>
1351 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1352 => "dent/newesim/dent"
1353 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1354 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1355 (database-name *default-database*)
1356 => "dent/newesim/dent"
1358 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1359 => "/template1/dent"
1360 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1361 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1362 (database-name *default-database*)
1363 => "/template1/dent"
1365 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1366 => "www.pmsf.de/template1/dent"
1368 (find-database "dent/newesim/dent")
1369 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1370 (find-database "/template1/dent")
1371 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1372 (find-database "www.pmsf.de/template1/dent" nil)
1375 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1379 <title>Side Effects</title>
1383 <title>Affected By</title>
1386 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1391 <title>Exceptional Situations</title>
1392 <para>Will signal an error of type
1393 <errortype>clsql-error</errortype> if no matching database
1394 can be found, and <parameter>errorp</parameter> is true.
1395 Will signal an error if the value of
1396 <parameter>database</parameter> is neither an object of type
1397 <type>database</type> nor a string.</para>
1400 <title>See Also</title>
1404 linkend="database-name"><function>database-name</function></link></member>
1406 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1407 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1408 <member><link linkend="connect"><function>connect</function></link></member>
1409 <member><link linkend="status"><function>status</function></link></member>
1410 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1415 <title>Notes</title>
1416 <para>The <parameter>db-type</parameter> keyword argument to
1417 <function>find-database</function> is a &clsql;
1422 <refentry id="initialize-database-type">
1424 <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
1427 <refname>INITIALIZE-DATABASE-TYPE</refname>
1428 <refpurpose>Initializes a database type</refpurpose>
1429 <refclass>Function</refclass>
1432 <title>Syntax</title>
1434 <function>initialize-database-type &key database-type</function> => <returnvalue>result</returnvalue></synopsis>
1437 <title>Arguments and Values</title>
1440 <term><parameter>database-type</parameter></term>
1442 <para>The database type to initialize, i.e. a keyword
1443 symbol denoting a known database back-end. Defaults to
1445 <symbol>*default-database-type*</symbol>.</para>
1449 <term><returnvalue>result</returnvalue></term>
1451 <para>Either &nil; if the initialization
1452 attempt fails, or <symbol>t</symbol> otherwise.</para>
1458 <title>Description</title>
1459 <para>If the back-end specified by
1460 <parameter>database-type</parameter> has not already been
1461 initialized, as seen from
1462 <symbol>*initialized-database-types*</symbol>, an attempt is
1463 made to initialize the database. If this attempt succeeds,
1464 or the back-end has already been initialized, the function
1465 returns t, and places the keyword denoting the database type
1466 onto the list stored in
1467 <symbol>*initialized-database-types*</symbol>, if not
1468 already present.</para>
1469 <para>If initialization fails, the function returns
1470 &nil;, and/or signals an error of type
1471 <errortype>clsql-error</errortype>. The kind of action
1472 taken depends on the back-end and the cause of the
1476 <title>Examples</title>
1478 *initialized-database-types*
1480 (setf *default-database-type* :mysql)
1482 (initialize-database-type)
1483 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
1484 >> Compiling Top-Level Form:
1487 *initialized-database-types*
1489 (initialize-database-type)
1491 *initialized-database-types*
1496 <title>Side Effects</title>
1497 <para>The database back-end corresponding to the database type
1498 specified is initialized, unless it has already been
1499 initialized. This can involve any number of other side
1500 effects, as determined by the back-end implementation (like
1501 e.g. loading of foreign code, calling of foreign code,
1502 networking operations, etc.). If initialization is
1503 attempted and succeeds, the
1504 <parameter>database-type</parameter> is pushed onto the list
1506 <symbol>*initialized-database-types*</symbol>.</para>
1509 <title>Affected by</title>
1512 <member><symbol>*default-database-type*</symbol></member>
1513 <member><symbol>*initialized-database-types*</symbol></member>
1518 <title>Exceptional Situations</title>
1519 <para>If an error is encountered during the initialization
1520 attempt, the back-end may signal errors of kind
1521 <errortype>clsql-error</errortype>.</para>
1524 <title>See Also</title>
1526 <member><link linkend="initialized-database-types"><function>*initialized-database-types*</function></link></member>
1527 <member><link linkend="default-database-type"><function>*default-database-type*</function></link></member>
1531 <title>Notes</title>
1536 <refentry id="reconnect">
1538 <refentrytitle>RECONNECT</refentrytitle>
1541 <refname>RECONNECT</refname>
1542 <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
1543 <refclass>Function</refclass>
1546 <title>Syntax</title>
1548 <function>reconnect</function> &key <parameter>database</parameter> <parameter>error</parameter> <parameter>force</parameter> => <returnvalue>result</returnvalue></synopsis>
1551 <title>Arguments and Values</title>
1554 <term><parameter>database</parameter></term>
1556 <para>The database to reconnect, which defaults to the
1557 database indicated by
1558 <symbol>*default-database*</symbol>.</para>
1562 <term><parameter>error</parameter></term>
1564 <para>A boolean flag indicating whether to signal an error
1565 if <parameter>database</parameter> is non-nil but cannot
1566 be found. The default value is &nil;.
1571 <term><parameter>force</parameter></term>
1573 <para>A Boolean indicating whether to signal an error if the
1574 database connection has been lost. The default value is &t;.
1579 <term><parameter>result</parameter></term>
1581 <para>A Boolean indicating whether the database was
1582 successfully reconnected.
1589 <title>Description</title>
1590 <para>Reconnects <parameter>database</parameter> which defaults
1591 to <symbol>*default-database*</symbol> to the underlying
1592 database management system. On success, &t; is returned and the
1593 variable <symbol>*default-database*</symbol> is set to the newly
1594 reconnected database. If <parameter>database</parameter> is a
1595 database instance, this object is closed. If
1596 <parameter>database</parameter> is a string, then a connected
1597 database whose name matches <parameter>database</parameter> is
1598 sought in the list of connected databases. If no matching
1599 database is found and <parameter>error</parameter> and
1600 <parameter>database</parameter> are both non-&nil; an error is
1601 signaled, otherwise &nil; is returned.</para>
1603 <para> When the current database connection has been lost, if
1604 <parameter>force</parameter> is non-&nil; as it is by default, the
1605 connection is closed and errors are suppressed. If
1606 <parameter>force</parameter> is &nil; and the database connection
1607 cannot be closed, an error is signalled.
1611 <title>Examples</title>
1614 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}>
1616 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}>
1620 <title>Side Effects</title>
1621 <para>A database connection is re-established and
1622 <symbol>*default-database*</symbol> may be rebound to the supplied
1623 database object.</para>
1626 <title>Affected by</title>
1629 <member><symbol>*default-database*</symbol></member>
1634 <title>Exceptional Situations</title>
1636 An error may be signalled if the specified database cannot be
1637 located or if the database cannot be closed.
1641 <title>See Also</title>
1645 linkend="connect"><function>connect</function></link></member>
1647 linkend="disconnect"><function>disconnect</function></link></member>
1649 linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1654 <title>Notes</title>
1661 <refentry id="status">
1663 <refentrytitle>STATUS</refentrytitle>
1666 <refname>STATUS</refname>
1667 <refpurpose>Print information about connected databases.</refpurpose>
1668 <refclass>Function</refclass>
1671 <title>Syntax</title>
1673 <function>status</function> &optional <parameter>full</parameter> => <returnvalue></returnvalue></synopsis>
1676 <title>Arguments and Values</title>
1679 <term><parameter>full</parameter></term>
1681 <para>A boolean indicating whether to print additional
1682 table information. The default value is &nil;.
1689 <title>Description</title>
1690 <para>Prints information about the currently connected databases
1691 to <symbol>*STANDARD-OUTPUT*</symbol>. The argument
1692 <parameter>full</parameter> is &nil; by default and a value of t
1693 means that more detailed information about each database is
1698 <title>Examples</title>
1702 CLSQL STATUS: 2004-06-13 15:07:39
1703 --------------------------------------------------------
1704 DATABASE TYPE RECORDING
1705 --------------------------------------------------------
1706 localhost/test/petrov mysql nil
1707 localhost/test/petrov postgresql nil
1708 localhost/test/petrov postgresql-socket nil
1709 test/petrov odbc nil
1710 * :memory: sqlite nil
1711 --------------------------------------------------------
1715 CLSQL STATUS: 2004-06-13 15:08:08
1716 -------------------------------------------------------------------------------
1717 DATABASE TYPE RECORDING POOLED TABLES VIEWS
1718 -------------------------------------------------------------------------------
1719 localhost/test/petrov mysql nil nil 7 0
1720 localhost/test/petrov postgresql nil nil 7 0
1721 localhost/test/petrov postgresql-socket nil nil 7 0
1722 test/petrov odbc nil nil 7 0
1723 * :memory: sqlite nil nil 0 0
1724 -------------------------------------------------------------------------------
1728 <title>Side Effects</title>
1734 <title>Affected by</title>
1740 <title>Exceptional Situations</title>
1746 <title>See Also</title>
1749 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1750 <member><link linkend="connect"><function>connect</function></link></member>
1751 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1752 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
1753 <member><link linkend="find-database"><function>find-database</function></link></member>
1758 <title>Notes</title>
1766 <!-- create/probe/list/destroytruncate-database -->
1768 <refentry id="create-database">
1770 <refentrytitle>CREATE-DATABASE</refentrytitle>
1773 <refname>CREATE-DATABASE</refname>
1774 <refpurpose>create a database</refpurpose>
1775 <refclass>Function</refclass>
1778 <title>Syntax</title>
1779 <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1782 <title>Arguments and Values</title>
1785 <term><parameter>connection-spec</parameter></term>
1787 <para>A connection specification</para>
1791 <term><parameter>database-type</parameter></term>
1793 <para>A database type specifier, i.e. a keyword.
1794 This defaults to the value of
1795 <symbol>*default-database-type*</symbol></para>
1799 <term><parameter>success</parameter></term>
1801 <para>A boolean flag. If &t;, a new database was
1802 successfully created.
1809 <title>Description</title>
1810 <para>This function creates a database in the database system
1811 specified by <parameter>database-type</parameter>.
1815 <title>Examples</title>
1817 (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
1820 (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
1822 Error: While trying to access database localhost/new/dent
1823 using database-type MYSQL:
1824 Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1825 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1827 [condition type: CLSQL-ACCESS-ERROR]
1831 <title>Side Effects</title>
1832 <para>A database will be created on the filesystem of the host.</para>
1835 <title>Exceptional Situations</title>
1836 <para>An exception will be thrown if the database system does
1837 not allow new databases to be created or if database creation
1841 <title>See Also</title>
1844 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1845 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1846 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1851 <title>Notes</title>
1852 <para>This function may invoke the operating systems
1853 functions. Thus, some database systems may require the
1854 administration functions to be available in the current
1855 <symbol>PATH</symbol>. At this time, the
1856 <symbol>:mysql</symbol> backend requires
1857 <filename>mysqladmin</filename> and the
1858 <symbol>:postgresql</symbol> backend requires
1859 <filename>createdb</filename>.</para>
1861 <function>create-database</function> is a &clsql; extension.
1866 <refentry id="destroy-database">
1868 <refentrytitle>DESTROY-DATABASE</refentrytitle>
1871 <refname>DESTROY-DATABASE</refname>
1872 <refpurpose>destroys a database</refpurpose>
1873 <refclass>Function</refclass>
1876 <title>Syntax</title>
1877 <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1880 <title>Arguments and Values</title>
1883 <term><parameter>connection-spec</parameter></term>
1885 <para>A connection specification</para>
1889 <term><parameter>database-type</parameter></term>
1891 <para>A database type specifier, i.e. a keyword.
1892 This defaults to the value of
1893 <symbol>*default-database-type*</symbol></para>
1897 <term><parameter>success</parameter></term>
1899 <para>A boolean flag. If &t;, the database was
1900 successfully destroyed.
1907 <title>Description</title>
1908 <para>This function destroys a database in the database system
1909 specified by <parameter>database-type</parameter>.
1913 <title>Examples</title>
1915 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1918 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1920 Error: While trying to access database localhost/test2/root
1921 using database-type POSTGRESQL:
1922 Error database-destroy failed: dropdb: database removal failed: ERROR: database "test2" does not exist
1924 [condition type: CLSQL-ACCESS-ERROR]
1928 <title>Side Effects</title>
1929 <para>A database will be removed from the filesystem of the host.</para>
1932 <title>Exceptional Situations</title>
1933 <para>An exception will be thrown if the database system does not
1934 allow databases to be removed, the database does not exist, or
1935 if database removal fails.</para>
1938 <title>See Also</title>
1941 <member><link linkend="create-database"><function>create-database</function></link></member>
1942 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1943 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1948 <title>Notes</title>
1949 <para>This function may invoke the operating systems
1950 functions. Thus, some database systems may require the
1951 administration functions to be available in the current
1952 <symbol>PATH</symbol>. At this time, the
1953 <symbol>:mysql</symbol> backend requires
1954 <filename>mysqladmin</filename> and the
1955 <symbol>:postgresql</symbol> backend requires
1956 <filename>dropdb</filename>.</para>
1958 <function>destroy-database</function> is a &clsql; extension.
1963 <refentry id="probe-database">
1965 <refentrytitle>PROBE-DATABASE</refentrytitle>
1968 <refname>PROBE-DATABASE</refname>
1969 <refpurpose>tests for existence of a database</refpurpose>
1970 <refclass>Function</refclass>
1973 <title>Syntax</title>
1974 <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1977 <title>Arguments and Values</title>
1980 <term><parameter>connection-spec</parameter></term>
1982 <para>A connection specification</para>
1986 <term><parameter>database-type</parameter></term>
1988 <para>A database type specifier, i.e. a keyword.
1989 This defaults to the value of
1990 <symbol>*default-database-type*</symbol></para>
1994 <term><parameter>success</parameter></term>
1996 <para>A boolean flag. If &t;, the database exists
1997 in the database system.
2004 <title>Description</title>
2005 <para>This function tests for the existence of a database in
2006 the database system specified by
2007 <parameter>database-type</parameter>.
2011 <title>Examples</title>
2013 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
2018 <title>Side Effects</title>
2022 <title>Exceptional Situations</title>
2023 <para>An exception maybe thrown if the database system does
2024 not receive administrator-level authentication since function
2025 may need to read the administrative database of the database
2029 <title>See Also</title>
2032 <member><link linkend="create-database"><function>create-database</function></link></member>
2033 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2034 <member><link linkend="list-databases"><function>list-databases</function></link></member>
2039 <title>Notes</title>
2041 <function>probe-database</function> is a &clsql; extension.
2046 <refentry id="list-databases">
2048 <refentrytitle>LIST-DATABASES</refentrytitle>
2051 <refname>LIST-DATABASES</refname>
2052 <refpurpose>List databases matching the supplied connection spec
2053 and database type.</refpurpose>
2054 <refclass>Function</refclass>
2057 <title>Syntax</title>
2059 <function>list-databases</function> <parameter>connection-spec</parameter> &key <parameter>database-type</parameter> => <returnvalue>result</returnvalue></synopsis>
2062 <title>Arguments and Values</title>
2065 <term><parameter>connection-spec</parameter></term>
2067 <para>A connection specification</para>
2071 <term><parameter>database-type</parameter></term>
2073 <para>A database type specifier, i.e. a keyword.
2074 This defaults to the value of
2075 <symbol>*default-database-type*</symbol></para>
2079 <term><parameter>result</parameter></term>
2081 <para>A list of matching databases.
2088 <title>Description</title>
2090 This function returns a list of databases existing in the
2091 database system specified by
2092 <parameter>database-type</parameter>.
2096 <title>Examples</title>
2098 (list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql)
2099 => ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test")
2103 <title>Side Effects</title>
2109 <title>Affected by</title>
2115 <title>Exceptional Situations</title>
2117 An exception maybe thrown if the database system does not
2118 receive administrator-level authentication since function may
2119 need to read the administrative database of the database
2124 <title>See Also</title>
2127 <member><link linkend="create-database"><function>create-database</function></link></member>
2128 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2129 <member><link linkend="probe-database"><function>probe-database</function></link></member>
2134 <title>Notes</title>
2136 <function>list-databases</function> is a &clsql; extension.
2142 <!-- with-database and with-default-database -->
2144 <refentry id="with-database">
2146 <refentrytitle>WITH-DATABASE</refentrytitle>
2149 <refname>WITH-DATABASE</refname>
2150 <refpurpose>Execute a body of code with a variable bound to a
2151 specified database object.</refpurpose>
2152 <refclass>Macro</refclass>
2155 <title>Syntax</title>
2157 <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>
2160 <title>Arguments and Values</title>
2163 <term><parameter>db-var</parameter></term>
2165 <para>A variable which is bound to the specified database.
2170 <term><parameter>connection-spec</parameter></term>
2172 <para>A vendor specific connection specification supplied
2173 as a list or as a string.</para>
2177 <term><parameter>connect-args</parameter></term>
2179 <para>Other optional arguments to
2180 <function>connect</function>. This macro use a value of
2181 &nil; for <function>connect</function>'s
2182 <replaceable>make-default</replaceable> key, This is in
2183 contrast to to the connect function which has a default
2184 value of &t; for <replaceable>make-default</replaceable>.
2189 <term><parameter>body</parameter></term>
2191 <para>A Lisp code body.
2196 <term><parameter>result</parameter></term>
2198 <para>Determined by the result of executing the last
2199 expression in <parameter>body</parameter>.
2206 <title>Description</title>
2207 <para>Evaluate <parameter>body</parameter> in an environment,
2208 where <parameter>db-var</parameter> is bound to the database
2209 connection given by <parameter>connection-spec</parameter> and
2210 <parameter>connect-args</parameter>. The connection is
2211 automatically closed or released to the pool on exit from the
2216 <title>Examples</title>
2218 (connected-databases)
2220 (with-database (db '(":memory:") :database-type :sqlite
2224 (connected-databases)
2229 <title>Side Effects</title>
2231 See <function>connect</function> and <function>disconnect</function>.
2235 <title>Affected by</title>
2237 See <function>connect</function> and <function>disconnect</function>.
2241 <title>Exceptional Situations</title>
2243 See <function>connect</function> and <function>disconnect</function>.
2247 <title>See Also</title>
2250 <member><link linkend="connect"><function>connect</function></link></member>
2251 <member><link linkend="disconnect"><function>disconnect</function></link></member>
2252 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
2253 <member><link linkend="with-default-database"><function>with-default-database</function></link></member>
2258 <title>Notes</title>
2260 <function>with-database</function> is a &clsql; extension.
2265 <refentry id="with-default-database">
2267 <refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
2270 <refname>WITH-DEFAULT-DATABASE</refname>
2271 <refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
2272 <refclass>Macro</refclass>
2275 <title>Syntax</title>
2277 <function>with-default-database</function> <replaceable>database</replaceable> &rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
2280 <title>Arguments and Values</title>
2283 <term><parameter>database</parameter></term>
2285 <para>An active database object.
2290 <term><parameter>body</parameter></term>
2292 <para>A Lisp code body.
2297 <term><parameter>result</parameter></term>
2299 <para>Determined by the result of executing the last
2300 expression in <parameter>body</parameter>.
2307 <title>Description</title>
2308 <para>Perform <parameter>body</parameter> with
2309 <parameter>DATABASE</parameter> bound as
2310 <symbol>*default-database*</symbol>.
2314 <title>Examples</title>
2317 => #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}>
2319 (let ((database (clsql:find-database ":memory:")))
2320 (with-default-database (database)
2321 (database-name *default-database*)))
2326 <title>Side Effects</title>
2332 <title>Affected by</title>
2338 <title>Exceptional Situations</title>
2340 Calls to &clsql; functions in <parameter>body</parameter> may signal
2341 errors if <parameter>database</parameter> is not an active database
2346 <title>See Also</title>
2349 <member><link linkend="with-database"><function>with-database</function></link></member>
2350 <member><link linkend="default-database"><symbol>*default-database*</symbol></link></member>
2355 <title>Notes</title>
2357 <function>with-default-database</function> is a &clsql; extension.