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
148 disconnect a database rather than returning it to the pool. NIL for
149 no limit. This is really a heuristic that should, on avg keep the
150 free connections about this size.</para>
152 <para>This is not a hard limit, the number of connections in
153 the pool may exceed this value.</para>
157 <title>Examples</title>
159 (setf clsql-sys:*db-pool-max-free-connections* 2)
163 <title>Affected By</title>
167 <title>See Also</title>
170 <member><link linkend="connect"><function>connect</function></link></member>
171 <member><link linkend="disconnect"><function>disconnect</function></link></member>
184 <refentry id="default-database">
186 <refentrytitle>*DEFAULT-DATABASE*</refentrytitle>
189 <refname>*DEFAULT-DATABASE*</refname>
190 <refpurpose>The default database object to use.</refpurpose>
191 <refclass>Variable</refclass>
194 <title>Value Type</title>
195 <para>Any object of type <type>database</type>, or &nil; to
196 indicate no default database.</para>
199 <title>Initial Value</title>
203 <title>Description</title>
204 <para>Any function or macro in &clsql; that operates on a
205 database uses the value of this variable as the default value
206 for it's <parameter>database</parameter> parameter.</para>
207 <para>The value of this parameter is changed by calls to
208 <function>connect</function>, which sets
209 <symbol>*default-database*</symbol> to the database object
210 it returns. It is also changed by calls to
211 <function>disconnect</function>, when the database object
212 being disconnected is the same as the value of
213 <symbol>*default-database*</symbol>. In this case
214 <function>disconnect</function> sets
215 <symbol>*default-database*</symbol> to the first database
216 that remains in the list of active databases as returned by
217 <function>connected-databases</function>, or
218 &nil; if no further active databases
220 <para>The user may change <symbol>*default-database*</symbol>
221 at any time to a valid value of his choice.</para>
223 <para>If the value of <symbol>*default-database*</symbol> is
224 &nil;, then all calls to &clsql; functions on
225 databases must provide a suitable
226 <parameter>database</parameter> parameter, or an error will be
231 <title>Examples</title>
233 (connected-databases)
235 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
236 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
237 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
238 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
239 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
240 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
242 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
246 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
250 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
255 (connected-databases)
260 <title>Affected By</title>
262 <member><link linkend="connect"><function>connect</function></link></member>
263 <member><link linkend="disconnect"><function>disconnect</function></link></member>
267 <title>See Also</title>
270 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
277 <para>This variable is intended to facilitate working with
278 &clsql; in an interactive
279 fashion at the top-level loop, and because of this,
280 <function>connect</function> and
281 <function>disconnect</function> provide some fairly
282 complex behaviour to keep
283 <symbol>*default-database*</symbol> set to useful values.
284 Programmatic use of &clsql;
285 should never depend on the value of
286 <symbol>*default-database*</symbol> and should provide
287 correct database objects via the
288 <parameter>database</parameter> parameter to functions
294 <refentry id="default-database-type">
296 <refentrytitle>*DEFAULT-DATABASE-TYPE*</refentrytitle>
299 <refname>*DEFAULT-DATABASE-TYPE*</refname>
300 <refpurpose>The default database type to use</refpurpose>
301 <refclass>Variable</refclass>
304 <title>Value Type</title>
305 <para>Any keyword representing a valid database back-end of
306 &clsql;, or &nil;.</para>
309 <title>Initial Value</title>
313 <title>Description</title>
314 <para>The value of this variable is used in calls to
315 <function>initialize-database-type</function> and
316 <function>connect</function> as the default value of the
317 <parameter>database-type</parameter> parameter.</para>
319 <para>If the value of this variable is &nil;,
321 <function>initialize-database-type</function> or
322 <function>connect</function> will have to specify the
323 <parameter>database-type</parameter> to use, or a
324 general-purpose error will be signalled.</para>
328 <title>Examples</title>
330 (setf *default-database-type* :mysql)
332 (initialize-database-type)
337 <title>Affected By</title>
341 <title>See Also</title>
344 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
353 <refentry id="initialized-database-types">
355 <refentrytitle>*INITIALIZED-DATABASE-TYPES*</refentrytitle>
358 <refname>*INITIALIZED-DATABASE-TYPES*</refname>
359 <refpurpose>List of all initialized database types</refpurpose>
360 <refclass>Variable</refclass>
363 <title>Value Type</title>
364 <para>A list of all initialized database types, each of which
365 represented by it's corresponding keyword.</para>
368 <title>Initial Value</title>
372 <title>Description</title>
373 <para>This variable is updated whenever
374 <function>initialize-database-type</function> is called for a
375 database type which hasn't already been initialized before, as
376 determined by this variable. In that case the keyword
377 representing the database type is pushed onto the list stored in
378 <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
380 <para>Attempts to modify the value of this variable will
381 result in undefined behaviour.</para>
385 <title>Examples</title>
387 (setf *default-database-type* :mysql)
389 (initialize-database-type)
391 *initialized-database-types*
396 <title>Affected By</title>
399 <member><function>initialize-database-type</function></member>
404 <title>See Also</title>
407 linkend="initialize-database-type"><function>intitialize-database-type</function></link></member>
412 <para>Direct access to this variable is primarily provided
413 because of compatibility with Harlequin's <application>Common
414 SQL</application>.</para>
418 <refentry id="connect">
420 <refentrytitle>CONNECT</refentrytitle>
423 <refname>CONNECT</refname>
424 <refpurpose>create a connection to a database.</refpurpose>
425 <refclass>Function</refclass>
428 <title>Syntax</title>
429 <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>
432 <title>Arguments and Values</title>
435 <term><parameter>connection-spec</parameter></term>
437 <para>A SQL backend specific connection specification
438 supplied as a list or as a string.</para>
439 <para>For the MySQL backend, this list includes an
440 optional associative list of connection options. The
441 options list is parsed and supplied to the MySQL API
442 using <function>mysql_options</function> in between the
443 calls to <function>mysql_init</function>
444 and <function>mysql_real_connect</function>.</para>
448 <term><parameter>if-exists</parameter></term>
450 <para>This indicates the action to take if a connection
451 to the same database exists already. See below for the
452 legal values and actions. It defaults to the value of
453 <symbol>*connect-if-exists*</symbol>.</para>
457 <term><parameter>database-type</parameter></term>
459 <para>A database type specifier, i.e. a keyword.
460 This defaults to the value of
461 <symbol>*default-database-type*</symbol></para>
465 <term><parameter>pool</parameter></term>
467 <para>A boolean flag. If &t;, acquire connection from a
468 pool of open connections. If the pool is empty, a new
469 connection is created. The default is &nil;.
474 <term><parameter>make-default</parameter></term>
476 <para>A boolean flag. If &t;,
477 <symbol>*default-database*</symbol> is set to the new
478 connection, otherwise <symbol>*default-database*</symbol>
479 is not changed. The default is &t;.
484 <term><returnvalue>database</returnvalue></term>
486 <para>The database object representing the connection.</para>
492 <title>Description</title>
493 <para>This function takes a connection specification and
494 a database type and creates a connection to the database
495 specified by those. The type and structure of the
496 connection specification depend on the database type.</para>
497 <para>The parameter <parameter>if-exists</parameter> specifies
498 what to do if a connection to the database specified exists
499 already, which is checked by calling
500 <function>find-database</function> on the database name
501 returned by <function>database-name-from-spec</function>
502 when called with the <parameter>connection-spec</parameter>
503 and <parameter>database-type</parameter> parameters. The
504 possible values of <parameter>if-exists</parameter> are:
507 <term><symbol>:new</symbol></term>
509 <para>Go ahead and create a new connection.</para>
513 <term><symbol>:warn-new</symbol></term>
515 <para>This is just like <symbol>:new</symbol>, but
516 also signals a warning of type
517 <errortype>clsql-exists-warning</errortype>,
518 indicating the old and newly created
523 <term><symbol>:error</symbol></term>
525 <para>This will cause <function>connect</function> to
526 signal a correctable error of type
527 <errortype>clsql-exists-error</errortype>. The
528 user may choose to proceed, either by indicating
529 that a new connection shall be created, via the
530 restart <symbol>create-new</symbol>, or by
531 indicating that the existing connection shall be
532 used, via the restart
533 <symbol>use-old</symbol>.</para>
537 <term><symbol>:old</symbol></term>
539 <para>This will cause <function>connect</function> to
540 use an old connection if one exists.</para>
544 <term><symbol>:warn-old</symbol></term>
546 <para>This is just like <symbol>:old</symbol>, but
547 also signals a warning of type
548 <errortype>clsql-exists-warning</errortype>,
549 indicating the old database used, via the slots
550 <symbol>old-db</symbol> and
551 <symbol>new-db</symbol></para>
556 <para>The database name of the returned database object will
557 be the same under <function>string=</function> as that which
558 would be returned by a call to
559 <function>database-name-from-spec</function> with the given
560 <parameter>connection-spec</parameter> and
561 <parameter>database-type</parameter> parameters.</para>
564 <title>Examples</title>
566 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
567 => "dent/newesim/dent"
568 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
569 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
571 => "dent/newesim/dent"
573 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
574 >> In call to CONNECT:
575 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
578 >> 0: [CREATE-NEW] Create a new connection.
579 >> 1: [USE-OLD ] Use the existing connection.
580 >> 2: [ABORT ] Return to Top-Level.
582 >> Debug (type H for help)
584 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
586 >> ; File: /prj/CLSQL/sql/sql.cl
587 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
588 >> (CREATE-NEW NIL :REPORT "Create a new connection."
590 >> (USE-OLD NIL :REPORT "Use the existing connection."
591 >> (SETQ RESULT OLD-DB)))
593 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
597 <title>Side Effects</title>
598 <para>A database connection is established, and the resultant
599 database object is registered, so as to appear in the list
600 returned by <function>connected-databases</function>.
601 <symbol>*default-database*</symbol> may be rebound to the
602 created object.</para>
605 <title>Affected by</title>
609 <link linkend="default-database-type">
610 <symbol>*default-database-type*</symbol>
614 <link linkend="connect-if-exists">
615 <symbol>*connect-if-exists*</symbol>
622 <title>Exceptional Situations</title>
623 <para>If the connection specification is not syntactically or
624 semantically correct for the given database type, an error of
625 type <errortype>sql-user-error</errortype> is
626 signalled. If during the connection attempt an error is
627 detected (e.g. because of permission problems, network trouble
628 or any other cause), an error of type
629 <errortype>sql-database-error</errortype> is signalled.</para>
630 <para>If a connection to the database specified by
631 <parameter>connection-spec</parameter> exists already,
632 conditions are signalled according to the
633 <parameter>if-exists</parameter> parameter, as described
637 <title>See Also</title>
639 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
640 <member><link linkend="disconnect"><function>disconnect</function></link></member>
641 <member><link linkend="reconnect"><function>reconnect</function></link></member>
642 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
643 <member><link linkend="find-database"><function>find-database</function></link></member>
644 <member><link linkend="status"><function>status</function></link></member>
649 <para>The <parameter>pool</parameter> and
650 <parameter>make-default</parameter> keyword arguments to
651 <function>connect</function> are &clsql; extensions.</para>
655 <refentry id="connected-databases">
657 <refentrytitle>CONNECTED-DATABASES</refentrytitle>
660 <refname>CONNECTED-DATABASES</refname>
661 <refpurpose>Return the list of active database objects.</refpurpose>
662 <refclass>Function</refclass>
665 <title>Syntax</title>
667 <function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
670 <title>Arguments and Values</title>
673 <term><returnvalue>databases</returnvalue></term>
675 <para>The list of active database objects.</para>
681 <title>Description</title>
682 <para>This function returns the list of active database
683 objects, i.e. all those database objects created by calls to
684 <function>connect</function>, which have not been closed by
685 calling <function>disconnect</function> on them.</para>
687 <para>The consequences of modifying the list returned by
688 <function>connected-databases</function> are
693 <title>Examples</title>
695 (connected-databases)
697 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
698 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
699 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
700 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
701 (connected-databases)
702 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
703 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
706 (connected-databases)
707 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
710 (connected-databases)
715 <title>Side Effects</title>
719 <title>Affected By</title>
722 <member><function>connect</function></member>
723 <member><function>disconnect</function></member>
728 <title>Exceptional Situations</title>
732 <title>See Also</title>
734 <member><link linkend="disconnect"><function>disconnect</function></link></member>
735 <member><link linkend="connect"><function>connect</function></link></member>
736 <member><link linkend="status"><function>status</function></link></member>
737 <member><link linkend="find-database"><function>find-database</function></link></member>
747 <refentry id="database-name">
749 <refentrytitle>DATABASE-NAME</refentrytitle>
752 <refname>DATABASE-NAME</refname>
753 <refpurpose>Get the name of a database object</refpurpose>
754 <refclass>Generic Function</refclass>
757 <title>Syntax</title>
758 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
761 <title>Arguments and Values</title>
764 <term><parameter>database</parameter></term>
766 <para>A database object, either of type
767 <type>database</type> or of type
768 <type>closed-database</type>.</para>
772 <term><returnvalue>name</returnvalue></term>
774 <para>A string describing the identity of the database
775 to which this database object is connected to.</para>
781 <title>Description</title>
782 <para>This function returns the database name of the given
783 database. The database name is a string which somehow
784 describes the identity of the database to which this
785 database object is or has been connected. The database name
786 of a database object is determined at
787 <function>connect</function> time, when a call to
788 <function>database-name-from-spec</function> derives the
789 database name from the connection specification passed to
790 <function>connect</function> in the
791 <parameter>connection-spec</parameter> parameter.</para>
792 <para>The database name is used via
793 <function>find-database</function> in
794 <function>connect</function> to determine whether database
795 connections to the specified database exist already.</para>
796 <para>Usually the database name string will include
797 indications of the host, database name, user, or port that
798 where used during the connection attempt. The only
799 important thing is that this string shall try to identify
800 the database at the other end of the connection. Connection
801 specifications parts like passwords and credentials shall
802 not be used as part of the database name.</para>
805 <title>Examples</title>
807 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
808 => "dent/newesim/dent"
809 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
810 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
811 (database-name *default-database*)
812 => "dent/newesim/dent"
814 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
816 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
817 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
818 (database-name *default-database*)
821 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
822 => "www.pmsf.de/template1/dent"
826 <title>Side Effects</title>
830 <title>Affected By</title>
833 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
838 <title>Exceptional Situations</title>
839 <para>Will signal an error if the object passed as the
840 <parameter>database</parameter> parameter is neither of type
841 <type>database</type> nor of type
842 <type>closed-database</type>.</para>
845 <title>See Also</title>
849 linkend="connect"><function>connect</function></link></member>
851 linkend="find-database"><function>find-database</function></link></member>
852 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
853 <member><link linkend="disconnect"><function>disconnect</function></link></member>
854 <member><link linkend="status"><function>status</function></link></member>
864 <refentry id="database-name-from-spec">
866 <refentrytitle>DATABASE-NAME-FROM-SPEC</refentrytitle>
869 <refname>DATABASE-NAME-FROM-SPEC</refname>
870 <refpurpose>Return the database name string corresponding to
871 the given connection specification.</refpurpose>
872 <refclass>Generic Function</refclass>
875 <title>Syntax</title>
877 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
880 <title>Arguments and Values</title>
883 <term><parameter>connection-spec</parameter></term>
885 <para>A connection specification, whose structure and
886 interpretation are dependent on the
887 <parameter>database-type</parameter>.</para>
891 <term><parameter>database-type</parameter></term>
893 <para>A database type specifier, i.e. a keyword.</para>
897 <term><returnvalue>name</returnvalue></term>
899 <para>A string denoting a database name.</para>
905 <title>Description</title>
906 <para>This generic function takes a connection specification
907 and a database type and returns the database name of the
908 database object that would be created had
909 <function>connect</function> been called with the given
910 connection specification and database types.</para>
911 <para>This function is useful in determining a database name
912 from the connection specification, since the way the
913 connection specification is converted into a database name
914 is dependent on the database type.</para>
917 <title>Examples</title>
919 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
920 => "dent/newesim/dent"
921 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
922 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
923 (database-name *default-database*)
924 => "dent/newesim/dent"
926 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
928 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
929 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
930 (database-name *default-database*)
933 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
934 => "www.pmsf.de/template1/dent"
936 (find-database "dent/newesim/dent")
937 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
938 (find-database "/template1/dent")
939 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
940 (find-database "www.pmsf.de/template1/dent" nil)
943 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
947 <title>Side Effects</title>
951 <title>Affected by</title>
955 <title>Exceptional Situations</title>
956 <para>If the value of <parameter>connection-spec</parameter>
957 is not a valid connection specification for the given
958 database type, an error of type
959 <errortype>clsql-invalid-spec-error</errortype> might be
963 <title>See Also</title>
966 <member><link linkend="connect"><function>connect</function></link></member>
972 <para><function>database-name-from-spec</function> is a
973 &clsql; extension.</para>
977 <refentry id="database-type">
979 <refentrytitle>DATABASE-TYPE</refentrytitle>
982 <refname>DATABASE-TYPE</refname>
983 <refpurpose>Get the type of a database object.</refpurpose>
984 <refclass>Generic Function</refclass>
987 <title>Syntax</title>
989 <function>database-type</function> <replaceable>DATABASE</replaceable> => <returnvalue>type</returnvalue></synopsis>
992 <title>Arguments and Values</title>
995 <term><parameter>database</parameter></term>
997 <para>A database object, either of type
998 <type>database</type> or of type
999 <type>closed-database</type>.</para>
1003 <term><returnvalue>type</returnvalue></term>
1005 <para>A keyword symbol denoting a known database back-end.</para>
1011 <title>Description</title>
1013 Returns the type of <parameter>database</parameter>.
1017 <title>Examples</title>
1019 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1020 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1021 (database-type *default-database*)
1026 <title>Side Effects</title>
1032 <title>Affected by</title>
1038 <title>Exceptional Situations</title>
1039 <para>Will signal an error if the object passed as the
1040 <parameter>database</parameter> parameter is neither of type
1041 <type>database</type> nor of type
1042 <type>closed-database</type>.</para>
1045 <title>See Also</title>
1049 linkend="connect"><function>connect</function></link></member>
1051 linkend="find-database"><function>find-database</function></link></member>
1052 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1053 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1054 <member><link linkend="status"><function>status</function></link></member>
1059 <title>Notes</title>
1061 <function>database-type</function> is a &clsql; extension.
1066 <refentry id="disconnect">
1068 <refentrytitle>DISCONNECT</refentrytitle>
1071 <refname>DISCONNECT</refname>
1072 <refpurpose>close a database connection</refpurpose>
1073 <refclass>Function</refclass>
1076 <title>Syntax</title>
1077 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>error</replaceable> => <returnvalue>result</returnvalue></synopsis>
1080 <title>Arguments and Values</title>
1083 <term><parameter>error</parameter></term>
1085 <para>A boolean flag indicating whether to signal an error
1086 if <parameter>database</parameter> is non-&nil; but cannot
1092 <term><parameter>database</parameter></term>
1094 <para>The database to disconnect, which defaults to the
1095 database indicated by
1096 <symbol>*default-database*</symbol>.</para>
1100 <term><parameter>result</parameter></term>
1102 <para>A Boolean indicating whether a connection was
1103 successfully disconnected.
1110 <title>Description</title>
1111 <para>This function takes a <type>database</type> object as
1112 returned by <function>connect</function>, and closes the
1113 connection. If no matching database is found and
1114 <parameter>error</parameter> and
1115 <parameter>database</parameter> are both non-&nil; an error is
1116 signaled, otherwise &nil; is returned. If the database is from a
1117 pool it will be released to this pool.
1120 <para>The status of the object passed is changed to closed
1121 after the disconnection succeeds, thereby preventing further
1122 use of the object as an argument to &clsql; functions, with
1123 the exception of <function>database-name</function> and
1124 <function>database-type</function>. If the user does pass a
1125 closed database to any other &clsql; function, an error of
1126 type <errortype>sql-fatal-error</errortype> is
1130 <title>Examples</title>
1132 (disconnect :database (find-database "dent/newesim/dent"))
1137 <title>Side Effects</title>
1138 <para>The database object is removed from the list of connected databases as
1139 returned by <link linkend="connected-databases"><function>connected-databases</function></link>.</para>
1140 <para>If the database object passed is the same under
1141 <function>eq</function> as the value of
1142 <symbol>*default-database*</symbol>, then
1143 <symbol>*default-database*</symbol> is set to the first
1144 remaining database from
1145 <function>connected-databases</function> or to &nil; if no
1146 further active database exists.</para>
1148 <title>Non-pooled</title>
1149 <para>The database connection is closed and the state of the
1150 database object is changed to <type>closed</type>.</para>
1153 <title>Pooled</title>
1154 <para>Unless there are already <link linkend="db-pool-max-free-connections">
1155 <symbol>*db-pool-max-free-connections*</symbol>
1156 </link> free connections in the pool it is returned to the
1157 pool, with the backend having an opportunity to run
1158 generic cleanup on the connection first. If the max free
1159 connections has already been reached then it is
1160 disconnected as if it were not in the pool.
1165 <title>Affected by</title>
1169 <link linkend="default-database">
1170 <symbol>*default-database*</symbol>
1174 <link linkend="db-pool-max-free-connections">
1175 <symbol>*db-pool-max-free-connections*</symbol>
1182 <title>Exceptional Situations</title>
1183 <para>If during the disconnection attempt an error is detected
1184 (e.g. because of network trouble or any other cause), an error
1185 of type <errortype>sql-error</errortype> might be
1189 <title>See Also</title>
1192 <member><link linkend="connect"><function>connect</function></link></member>
1193 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1198 <title>Notes</title>
1203 <refentry id="disconnect-pooled">
1205 <refentrytitle>DISCONNECT-POOLED</refentrytitle>
1208 <refname>DISCONNECT-POOLED</refname>
1209 <refpurpose>closes all pooled database connections</refpurpose>
1210 <refclass>Function</refclass>
1213 <title>Syntax</title>
1214 <synopsis><function>disconnect-pooled</function> &optional <symbol>clear</symbol> => <returnvalue>t</returnvalue></synopsis>
1217 <title>Description</title>
1218 <para>This function disconnects all database connections
1219 that have been placed into the pool by calling <link
1220 linkend="connect"><function>connect</function></link> with
1223 <para>If optional argument <symbol>clear</symbol> is non-&nil;
1224 then the connection-pool objects are also removed.</para>
1227 <title>Examples</title>
1234 <title>Side Effects</title>
1235 <para>Database connections will be closed and *all* entries in
1236 the pool are removed. This is done with great prejudice and no
1237 thought to thread safety or whether that connection is
1238 currently in use.</para>
1241 <title>Affected by</title>
1244 <member><function>disconnect</function></member>
1249 <title>Exceptional Situations</title>
1250 <para>If during the disconnection attempt an error is
1251 detected (e.g. because of network trouble or any other
1252 cause), an error of type <errortype>clsql-error</errortype>
1253 might be signalled.</para>
1256 <title>See Also</title>
1259 <member><link linkend="connect"><function>connect</function></link></member>
1260 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1265 <title>Notes</title>
1266 <para><function>disconnect-pooled</function> is a &clsql;
1271 <refentry id="find-database">
1273 <refentrytitle>FIND-DATABASE</refentrytitle>
1276 <refname>FIND-DATABASE</refname>
1277 <refpurpose>>Locate a database object through it's
1279 <refclass>Function</refclass>
1282 <title>Syntax</title>
1283 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1286 <title>Arguments and Values</title>
1289 <term><parameter>database</parameter></term>
1291 <para>A database object or a string, denoting a database
1296 <term><parameter>errorp</parameter></term>
1298 <para>A generalized boolean. Defaults to
1299 <symbol>t</symbol>.</para>
1303 <term><parameter>db-type</parameter></term>
1306 A keyword symbol denoting a known database back-end.
1311 <term><returnvalue>result</returnvalue></term>
1313 <para>Either a database object, or, if
1314 <parameter>errorp</parameter> is &nil;,
1315 possibly &nil;.</para>
1321 <title>Description</title>
1322 <para><function>find-database</function> locates an active
1323 database object given the specification in
1324 <parameter>database</parameter>. If
1325 <parameter>database</parameter> is an object of type
1326 <type>database</type>, <function>find-database</function>
1327 returns this. Otherwise it will search the active databases
1328 as indicated by the list returned by
1329 <function>connected-databases</function> for a database of
1330 type <parameter>db-type</parameter> whose name (as returned by
1331 <function>database-name</function> is equal as per
1332 <function>string=</function> to the string passed as
1333 <parameter>database</parameter>. If it succeeds, it returns
1334 the first database found.</para>
1336 If <parameter>db-type</parameter> is &nil; all databases
1337 matching the string <parameter>database</parameter> are
1338 considered. If no matching databases are found and
1339 <parameter>errorp</parameter> is &nil; then &nil; is
1340 returned. If <parameter>errorp</parameter> is &nil; and one or
1341 more matching databases are found, then the most recently
1342 connected database is returned as a first value and the
1343 number of matching databases is returned as a second
1344 value. If no, or more than one, matching databases are found
1345 and <parameter>errorp</parameter> is true, an error is
1350 <title>Examples</title>
1352 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1353 => "dent/newesim/dent"
1354 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1355 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1356 (database-name *default-database*)
1357 => "dent/newesim/dent"
1359 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1360 => "/template1/dent"
1361 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1362 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1363 (database-name *default-database*)
1364 => "/template1/dent"
1366 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1367 => "www.pmsf.de/template1/dent"
1369 (find-database "dent/newesim/dent")
1370 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1371 (find-database "/template1/dent")
1372 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1373 (find-database "www.pmsf.de/template1/dent" nil)
1376 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1380 <title>Side Effects</title>
1384 <title>Affected By</title>
1387 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1392 <title>Exceptional Situations</title>
1393 <para>Will signal an error of type
1394 <errortype>clsql-error</errortype> if no matching database
1395 can be found, and <parameter>errorp</parameter> is true.
1396 Will signal an error if the value of
1397 <parameter>database</parameter> is neither an object of type
1398 <type>database</type> nor a string.</para>
1401 <title>See Also</title>
1405 linkend="database-name"><function>database-name</function></link></member>
1407 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1408 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1409 <member><link linkend="connect"><function>connect</function></link></member>
1410 <member><link linkend="status"><function>status</function></link></member>
1411 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1416 <title>Notes</title>
1417 <para>The <parameter>db-type</parameter> keyword argument to
1418 <function>find-database</function> is a &clsql;
1423 <refentry id="initialize-database-type">
1425 <refentrytitle>INITIALIZE-DATABASE-TYPE</refentrytitle>
1428 <refname>INITIALIZE-DATABASE-TYPE</refname>
1429 <refpurpose>Initializes a database type</refpurpose>
1430 <refclass>Function</refclass>
1433 <title>Syntax</title>
1435 <function>initialize-database-type &key database-type</function> => <returnvalue>result</returnvalue></synopsis>
1438 <title>Arguments and Values</title>
1441 <term><parameter>database-type</parameter></term>
1443 <para>The database type to initialize, i.e. a keyword
1444 symbol denoting a known database back-end. Defaults to
1446 <symbol>*default-database-type*</symbol>.</para>
1450 <term><returnvalue>result</returnvalue></term>
1452 <para>Either &nil; if the initialization
1453 attempt fails, or <symbol>t</symbol> otherwise.</para>
1459 <title>Description</title>
1460 <para>If the back-end specified by
1461 <parameter>database-type</parameter> has not already been
1462 initialized, as seen from
1463 <symbol>*initialized-database-types*</symbol>, an attempt is
1464 made to initialize the database. If this attempt succeeds,
1465 or the back-end has already been initialized, the function
1466 returns t, and places the keyword denoting the database type
1467 onto the list stored in
1468 <symbol>*initialized-database-types*</symbol>, if not
1469 already present.</para>
1470 <para>If initialization fails, the function returns
1471 &nil;, and/or signals an error of type
1472 <errortype>clsql-error</errortype>. The kind of action
1473 taken depends on the back-end and the cause of the
1477 <title>Examples</title>
1479 *initialized-database-types*
1481 (setf *default-database-type* :mysql)
1483 (initialize-database-type)
1484 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
1485 >> Compiling Top-Level Form:
1488 *initialized-database-types*
1490 (initialize-database-type)
1492 *initialized-database-types*
1497 <title>Side Effects</title>
1498 <para>The database back-end corresponding to the database type
1499 specified is initialized, unless it has already been
1500 initialized. This can involve any number of other side
1501 effects, as determined by the back-end implementation (like
1502 e.g. loading of foreign code, calling of foreign code,
1503 networking operations, etc.). If initialization is
1504 attempted and succeeds, the
1505 <parameter>database-type</parameter> is pushed onto the list
1507 <symbol>*initialized-database-types*</symbol>.</para>
1510 <title>Affected by</title>
1513 <member><symbol>*default-database-type*</symbol></member>
1514 <member><symbol>*initialized-database-types*</symbol></member>
1519 <title>Exceptional Situations</title>
1520 <para>If an error is encountered during the initialization
1521 attempt, the back-end may signal errors of kind
1522 <errortype>clsql-error</errortype>.</para>
1525 <title>See Also</title>
1527 <member><link linkend="initialized-database-types"><function>*initialized-database-types*</function></link></member>
1528 <member><link linkend="default-database-type"><function>*default-database-type*</function></link></member>
1532 <title>Notes</title>
1537 <refentry id="reconnect">
1539 <refentrytitle>RECONNECT</refentrytitle>
1542 <refname>RECONNECT</refname>
1543 <refpurpose>Re-establishes the connection between a database object and its RDBMS.</refpurpose>
1544 <refclass>Function</refclass>
1547 <title>Syntax</title>
1549 <function>reconnect</function> &key <parameter>database</parameter> <parameter>error</parameter> <parameter>force</parameter> => <returnvalue>result</returnvalue></synopsis>
1552 <title>Arguments and Values</title>
1555 <term><parameter>database</parameter></term>
1557 <para>The database to reconnect, which defaults to the
1558 database indicated by
1559 <symbol>*default-database*</symbol>.</para>
1563 <term><parameter>error</parameter></term>
1565 <para>A boolean flag indicating whether to signal an error
1566 if <parameter>database</parameter> is non-nil but cannot
1567 be found. The default value is &nil;.
1572 <term><parameter>force</parameter></term>
1574 <para>A Boolean indicating whether to signal an error if the
1575 database connection has been lost. The default value is &t;.
1580 <term><parameter>result</parameter></term>
1582 <para>A Boolean indicating whether the database was
1583 successfully reconnected.
1590 <title>Description</title>
1591 <para>Reconnects <parameter>database</parameter> which defaults
1592 to <symbol>*default-database*</symbol> to the underlying
1593 database management system. On success, &t; is returned and the
1594 variable <symbol>*default-database*</symbol> is set to the newly
1595 reconnected database. If <parameter>database</parameter> is a
1596 database instance, this object is closed. If
1597 <parameter>database</parameter> is a string, then a connected
1598 database whose name matches <parameter>database</parameter> is
1599 sought in the list of connected databases. If no matching
1600 database is found and <parameter>error</parameter> and
1601 <parameter>database</parameter> are both non-&nil; an error is
1602 signaled, otherwise &nil; is returned.</para>
1604 <para> When the current database connection has been lost, if
1605 <parameter>force</parameter> is non-&nil; as it is by default, the
1606 connection is closed and errors are suppressed. If
1607 <parameter>force</parameter> is &nil; and the database connection
1608 cannot be closed, an error is signalled.
1612 <title>Examples</title>
1615 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}>
1617 => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}>
1621 <title>Side Effects</title>
1622 <para>A database connection is re-established and
1623 <symbol>*default-database*</symbol> may be rebound to the supplied
1624 database object.</para>
1627 <title>Affected by</title>
1630 <member><symbol>*default-database*</symbol></member>
1635 <title>Exceptional Situations</title>
1637 An error may be signalled if the specified database cannot be
1638 located or if the database cannot be closed.
1642 <title>See Also</title>
1646 linkend="connect"><function>connect</function></link></member>
1648 linkend="disconnect"><function>disconnect</function></link></member>
1650 linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
1655 <title>Notes</title>
1662 <refentry id="status">
1664 <refentrytitle>STATUS</refentrytitle>
1667 <refname>STATUS</refname>
1668 <refpurpose>Print information about connected databases.</refpurpose>
1669 <refclass>Function</refclass>
1672 <title>Syntax</title>
1674 <function>status</function> &optional <parameter>full</parameter> => <returnvalue></returnvalue></synopsis>
1677 <title>Arguments and Values</title>
1680 <term><parameter>full</parameter></term>
1682 <para>A boolean indicating whether to print additional
1683 table information. The default value is &nil;.
1690 <title>Description</title>
1691 <para>Prints information about the currently connected databases
1692 to <symbol>*STANDARD-OUTPUT*</symbol>. The argument
1693 <parameter>full</parameter> is &nil; by default and a value of t
1694 means that more detailed information about each database is
1699 <title>Examples</title>
1703 CLSQL STATUS: 2004-06-13 15:07:39
1704 --------------------------------------------------------
1705 DATABASE TYPE RECORDING
1706 --------------------------------------------------------
1707 localhost/test/petrov mysql nil
1708 localhost/test/petrov postgresql nil
1709 localhost/test/petrov postgresql-socket nil
1710 test/petrov odbc nil
1711 * :memory: sqlite nil
1712 --------------------------------------------------------
1716 CLSQL STATUS: 2004-06-13 15:08:08
1717 -------------------------------------------------------------------------------
1718 DATABASE TYPE RECORDING POOLED TABLES VIEWS
1719 -------------------------------------------------------------------------------
1720 localhost/test/petrov mysql nil nil 7 0
1721 localhost/test/petrov postgresql nil nil 7 0
1722 localhost/test/petrov postgresql-socket nil nil 7 0
1723 test/petrov odbc nil nil 7 0
1724 * :memory: sqlite nil nil 0 0
1725 -------------------------------------------------------------------------------
1729 <title>Side Effects</title>
1735 <title>Affected by</title>
1741 <title>Exceptional Situations</title>
1747 <title>See Also</title>
1750 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1751 <member><link linkend="connect"><function>connect</function></link></member>
1752 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1753 <member><link linkend="connect-if-exists"><function>*connect-if-exists*</function></link></member>
1754 <member><link linkend="find-database"><function>find-database</function></link></member>
1759 <title>Notes</title>
1767 <!-- create/probe/list/destroytruncate-database -->
1769 <refentry id="create-database">
1771 <refentrytitle>CREATE-DATABASE</refentrytitle>
1774 <refname>CREATE-DATABASE</refname>
1775 <refpurpose>create a database</refpurpose>
1776 <refclass>Function</refclass>
1779 <title>Syntax</title>
1780 <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1783 <title>Arguments and Values</title>
1786 <term><parameter>connection-spec</parameter></term>
1788 <para>A connection specification</para>
1792 <term><parameter>database-type</parameter></term>
1794 <para>A database type specifier, i.e. a keyword.
1795 This defaults to the value of
1796 <symbol>*default-database-type*</symbol></para>
1800 <term><parameter>success</parameter></term>
1802 <para>A boolean flag. If &t;, a new database was
1803 successfully created.
1810 <title>Description</title>
1811 <para>This function creates a database in the database system
1812 specified by <parameter>database-type</parameter>.
1816 <title>Examples</title>
1818 (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
1821 (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
1823 Error: While trying to access database localhost/new/dent
1824 using database-type MYSQL:
1825 Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1826 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1828 [condition type: CLSQL-ACCESS-ERROR]
1832 <title>Side Effects</title>
1833 <para>A database will be created on the filesystem of the host.</para>
1836 <title>Exceptional Situations</title>
1837 <para>An exception will be thrown if the database system does
1838 not allow new databases to be created or if database creation
1842 <title>See Also</title>
1845 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
1846 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1847 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1852 <title>Notes</title>
1853 <para>This function may invoke the operating systems
1854 functions. Thus, some database systems may require the
1855 administration functions to be available in the current
1856 <symbol>PATH</symbol>. At this time, the
1857 <symbol>:mysql</symbol> backend requires
1858 <filename>mysqladmin</filename> and the
1859 <symbol>:postgresql</symbol> backend requires
1860 <filename>createdb</filename>.</para>
1862 <function>create-database</function> is a &clsql; extension.
1867 <refentry id="destroy-database">
1869 <refentrytitle>DESTROY-DATABASE</refentrytitle>
1872 <refname>DESTROY-DATABASE</refname>
1873 <refpurpose>destroys a database</refpurpose>
1874 <refclass>Function</refclass>
1877 <title>Syntax</title>
1878 <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1881 <title>Arguments and Values</title>
1884 <term><parameter>connection-spec</parameter></term>
1886 <para>A connection specification</para>
1890 <term><parameter>database-type</parameter></term>
1892 <para>A database type specifier, i.e. a keyword.
1893 This defaults to the value of
1894 <symbol>*default-database-type*</symbol></para>
1898 <term><parameter>success</parameter></term>
1900 <para>A boolean flag. If &t;, the database was
1901 successfully destroyed.
1908 <title>Description</title>
1909 <para>This function destroys a database in the database system
1910 specified by <parameter>database-type</parameter>.
1914 <title>Examples</title>
1916 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1919 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1921 Error: While trying to access database localhost/test2/root
1922 using database-type POSTGRESQL:
1923 Error database-destroy failed: dropdb: database removal failed: ERROR: database "test2" does not exist
1925 [condition type: CLSQL-ACCESS-ERROR]
1929 <title>Side Effects</title>
1930 <para>A database will be removed from the filesystem of the host.</para>
1933 <title>Exceptional Situations</title>
1934 <para>An exception will be thrown if the database system does not
1935 allow databases to be removed, the database does not exist, or
1936 if database removal fails.</para>
1939 <title>See Also</title>
1942 <member><link linkend="create-database"><function>create-database</function></link></member>
1943 <member><link linkend="probe-database"><function>probe-database</function></link></member>
1944 <member><link linkend="list-databases"><function>list-databases</function></link></member>
1949 <title>Notes</title>
1950 <para>This function may invoke the operating systems
1951 functions. Thus, some database systems may require the
1952 administration functions to be available in the current
1953 <symbol>PATH</symbol>. At this time, the
1954 <symbol>:mysql</symbol> backend requires
1955 <filename>mysqladmin</filename> and the
1956 <symbol>:postgresql</symbol> backend requires
1957 <filename>dropdb</filename>.</para>
1959 <function>destroy-database</function> is a &clsql; extension.
1964 <refentry id="probe-database">
1966 <refentrytitle>PROBE-DATABASE</refentrytitle>
1969 <refname>PROBE-DATABASE</refname>
1970 <refpurpose>tests for existence of a database</refpurpose>
1971 <refclass>Function</refclass>
1974 <title>Syntax</title>
1975 <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1978 <title>Arguments and Values</title>
1981 <term><parameter>connection-spec</parameter></term>
1983 <para>A connection specification</para>
1987 <term><parameter>database-type</parameter></term>
1989 <para>A database type specifier, i.e. a keyword.
1990 This defaults to the value of
1991 <symbol>*default-database-type*</symbol></para>
1995 <term><parameter>success</parameter></term>
1997 <para>A boolean flag. If &t;, the database exists
1998 in the database system.
2005 <title>Description</title>
2006 <para>This function tests for the existence of a database in
2007 the database system specified by
2008 <parameter>database-type</parameter>.
2012 <title>Examples</title>
2014 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
2019 <title>Side Effects</title>
2023 <title>Exceptional Situations</title>
2024 <para>An exception maybe thrown if the database system does
2025 not receive administrator-level authentication since function
2026 may need to read the administrative database of the database
2030 <title>See Also</title>
2033 <member><link linkend="create-database"><function>create-database</function></link></member>
2034 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2035 <member><link linkend="list-databases"><function>list-databases</function></link></member>
2040 <title>Notes</title>
2042 <function>probe-database</function> is a &clsql; extension.
2047 <refentry id="list-databases">
2049 <refentrytitle>LIST-DATABASES</refentrytitle>
2052 <refname>LIST-DATABASES</refname>
2053 <refpurpose>List databases matching the supplied connection spec
2054 and database type.</refpurpose>
2055 <refclass>Function</refclass>
2058 <title>Syntax</title>
2060 <function>list-databases</function> <parameter>connection-spec</parameter> &key <parameter>database-type</parameter> => <returnvalue>result</returnvalue></synopsis>
2063 <title>Arguments and Values</title>
2066 <term><parameter>connection-spec</parameter></term>
2068 <para>A connection specification</para>
2072 <term><parameter>database-type</parameter></term>
2074 <para>A database type specifier, i.e. a keyword.
2075 This defaults to the value of
2076 <symbol>*default-database-type*</symbol></para>
2080 <term><parameter>result</parameter></term>
2082 <para>A list of matching databases.
2089 <title>Description</title>
2091 This function returns a list of databases existing in the
2092 database system specified by
2093 <parameter>database-type</parameter>.
2097 <title>Examples</title>
2099 (list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql)
2100 => ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test")
2104 <title>Side Effects</title>
2110 <title>Affected by</title>
2116 <title>Exceptional Situations</title>
2118 An exception maybe thrown if the database system does not
2119 receive administrator-level authentication since function may
2120 need to read the administrative database of the database
2125 <title>See Also</title>
2128 <member><link linkend="create-database"><function>create-database</function></link></member>
2129 <member><link linkend="destroy-database"><function>destroy-database</function></link></member>
2130 <member><link linkend="probe-database"><function>probe-database</function></link></member>
2135 <title>Notes</title>
2137 <function>list-databases</function> is a &clsql; extension.
2143 <!-- with-database and with-default-database -->
2145 <refentry id="with-database">
2147 <refentrytitle>WITH-DATABASE</refentrytitle>
2150 <refname>WITH-DATABASE</refname>
2151 <refpurpose>Execute a body of code with a variable bound to a
2152 specified database object.</refpurpose>
2153 <refclass>Macro</refclass>
2156 <title>Syntax</title>
2158 <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>
2161 <title>Arguments and Values</title>
2164 <term><parameter>db-var</parameter></term>
2166 <para>A variable which is bound to the specified database.
2171 <term><parameter>connection-spec</parameter></term>
2173 <para>A vendor specific connection specification supplied
2174 as a list or as a string.</para>
2178 <term><parameter>connect-args</parameter></term>
2180 <para>Other optional arguments to
2181 <function>connect</function>. This macro use a value of
2182 &nil; for <function>connect</function>'s
2183 <replaceable>make-default</replaceable> key, This is in
2184 contrast to to the connect function which has a default
2185 value of &t; for <replaceable>make-default</replaceable>.
2190 <term><parameter>body</parameter></term>
2192 <para>A Lisp code body.
2197 <term><parameter>result</parameter></term>
2199 <para>Determined by the result of executing the last
2200 expression in <parameter>body</parameter>.
2207 <title>Description</title>
2208 <para>Evaluate <parameter>body</parameter> in an environment,
2209 where <parameter>db-var</parameter> is bound to the database
2210 connection given by <parameter>connection-spec</parameter> and
2211 <parameter>connect-args</parameter>. The connection is
2212 automatically closed or released to the pool on exit from the
2217 <title>Examples</title>
2219 (connected-databases)
2221 (with-database (db '(":memory:") :database-type :sqlite
2225 (connected-databases)
2230 <title>Side Effects</title>
2232 See <function>connect</function> and <function>disconnect</function>.
2236 <title>Affected by</title>
2238 See <function>connect</function> and <function>disconnect</function>.
2242 <title>Exceptional Situations</title>
2244 See <function>connect</function> and <function>disconnect</function>.
2248 <title>See Also</title>
2251 <member><link linkend="connect"><function>connect</function></link></member>
2252 <member><link linkend="disconnect"><function>disconnect</function></link></member>
2253 <member><link linkend="disconnect-pooled"><function>disconnect-pooled</function></link></member>
2254 <member><link linkend="with-default-database"><function>with-default-database</function></link></member>
2259 <title>Notes</title>
2261 <function>with-database</function> is a &clsql; extension.
2266 <refentry id="with-default-database">
2268 <refentrytitle>WITH-DEFAULT-DATABASE</refentrytitle>
2271 <refname>WITH-DEFAULT-DATABASE</refname>
2272 <refpurpose>Execute a body of code with <symbol>*default-database*</symbol> bound to a specified database.</refpurpose>
2273 <refclass>Macro</refclass>
2276 <title>Syntax</title>
2278 <function>with-default-database</function> <replaceable>database</replaceable> &rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
2281 <title>Arguments and Values</title>
2284 <term><parameter>database</parameter></term>
2286 <para>An active database object.
2291 <term><parameter>body</parameter></term>
2293 <para>A Lisp code body.
2298 <term><parameter>result</parameter></term>
2300 <para>Determined by the result of executing the last
2301 expression in <parameter>body</parameter>.
2308 <title>Description</title>
2309 <para>Perform <parameter>body</parameter> with
2310 <parameter>DATABASE</parameter> bound as
2311 <symbol>*default-database*</symbol>.
2315 <title>Examples</title>
2318 => #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}>
2320 (let ((database (clsql:find-database ":memory:")))
2321 (with-default-database (database)
2322 (database-name *default-database*)))
2327 <title>Side Effects</title>
2333 <title>Affected by</title>
2339 <title>Exceptional Situations</title>
2341 Calls to &clsql; functions in <parameter>body</parameter> may signal
2342 errors if <parameter>database</parameter> is not an active database
2347 <title>See Also</title>
2350 <member><link linkend="with-database"><function>with-database</function></link></member>
2351 <member><link linkend="default-database"><symbol>*default-database*</symbol></link></member>
2356 <title>Notes</title>
2358 <function>with-default-database</function> is a &clsql; extension.