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">
9 <title><symbol>CLSQL</symbol></title>
11 <para>This part gives a reference to the symbols exported from the
12 <symbol>CLSQL</symbol> package. These symbols constitute
13 the normal user-interface of &clsql;. Currently, the symbols of
14 the &commonsql;-API are not documented here.</para>
17 <refentry id="sql-condition">
19 <refname>SQL-CONDITION</refname>
20 <refpurpose>the super-type of all
22 conditions</refpurpose>
23 <refclass>Condition Type</refclass>
26 <title>Class Precedence List</title>
28 <simplelist type="inline">
29 <member><errortype>sql-condition</errortype></member>
30 <member><errortype>condition</errortype></member>
31 <member><errortype>t</errortype></member>
36 <title>Description</title>
37 <para>This is the super-type of all
38 &clsql;-specific conditions
39 defined by &clsql;, or any of it's
40 database-specific interfaces. There are no defined
41 initialization arguments nor any accessors.</para>
44 <refentry id="sql-error">
46 <refname>SQL-ERROR</refname>
47 <refpurpose>the super-type of all
50 <refclass>Condition Type</refclass>
53 <title>Class Precedence List</title>
55 <simplelist type="inline">
56 <member><errortype>sql-error</errortype></member>
57 <member><errortype>error</errortype></member>
58 <member><errortype>serious-condition</errortype></member>
59 <member><errortype>sql-condition</errortype></member>
60 <member><errortype>condition</errortype></member>
61 <member><errortype>t</errortype></member>
66 <title>Description</title>
67 <para>This is the super-type of all
68 &clsql;-specific conditions that
69 represent errors, as defined by
70 &clsql;, or any of it's
71 database-specific interfaces. There are no defined
72 initialization arguments nor any accessors.</para>
75 <refentry id="sql-warning">
77 <refname>SQL-WARNING</refname>
78 <refpurpose>the super-type of all
81 <refclass>Condition Type</refclass>
84 <title>Class Precedence List</title>
86 <simplelist type="inline">
87 <member><errortype>sql-warning</errortype></member>
88 <member><errortype>warning</errortype></member>
89 <member><errortype>sql-condition</errortype></member>
90 <member><errortype>condition</errortype></member>
91 <member><errortype>t</errortype></member>
96 <title>Description</title>
97 <para>This is the super-type of all
98 &clsql;-specific conditions that
99 represent warnings, as defined by
100 &clsql;, or any of it's
101 database-specific interfaces. There are no defined
102 initialization arguments nor any accessors.</para>
105 <!-- Specifc Conditions -->
106 <refentry id="sql-user-error">
108 <refname>CLSQL-USER-ERROR</refname>
109 <refpurpose>condition representing errors because of invalid
110 parameters from the library user.</refpurpose>
111 <refclass>Condition Type</refclass>
114 <title>Class Precedence List</title>
116 <simplelist type="inline">
117 <member><errortype>sql-error</errortype></member>
118 <member><errortype>sql-condition</errortype></member>
119 <member><errortype>condition</errortype></member>
120 <member><errortype>t</errortype></member>
125 <title>Description</title>
126 <para>This condition represents errors that occur because the
127 user supplies invalid data to &clsql;. This includes errors such as
128 an invalid format connection specification or an error in the syntax
129 for the <function>LOOP</function> macro extensions.</para>
132 <refentry id="sql-connection-error">
134 <refname>SQL-CONNECTION-ERROR</refname>
135 <refpurpose>condition representing errors during
136 connection</refpurpose>
137 <refclass>Condition Type</refclass>
140 <title>Class Precedence List</title>
142 <simplelist type="inline">
143 <member><errortype>sql-connection-error</errortype></member>
144 <member><errortype>sql-database-error</errortype></member>
145 <member><errortype>sql-error</errortype></member>
146 <member><errortype>sql-condition</errortype></member>
147 <member><errortype>condition</errortype></member>
148 <member><errortype>t</errortype></member>
153 <title>Description</title>
154 <para>This condition represents errors that occur while trying
155 to connect to a database. The following initialization
156 arguments and accessors exist:</para>
158 <segtitle>Initarg</segtitle>
159 <segtitle>Accessor</segtitle>
160 <segtitle>Description</segtitle>
162 <seg><symbol>:database-type</symbol></seg>
163 <seg><function>sql-connection-error-database-type</function></seg>
164 <seg>Database type for the connection attempt</seg>
167 <seg><symbol>:connection-spec</symbol></seg>
168 <seg><function>sql-connection-error-connection-spec</function></seg>
169 <seg>The connection specification used in the
170 connection attempt.</seg>
173 <seg><symbol>:errno</symbol></seg>
174 <seg><function>sql-connection-error-errno</function></seg>
175 <seg>The numeric or symbolic error specification
176 returned by the database back-end. The values and
177 semantics of this are interface specific.</seg>
180 <seg><symbol>:error</symbol></seg>
181 <seg><function>sql-connection-error-error</function></seg>
182 <seg>A string describing the problem that occurred,
183 possibly one returned by the database back-end.</seg>
188 <refentry id="sql-database-error">
190 <refname>SQL-DATABASE-ERROR</refname>
191 <refpurpose>condition representing errors during query or
192 command execution</refpurpose>
193 <refclass>Condition Type</refclass>
196 <title>Class Precedence List</title>
198 <simplelist type="inline">
199 <member><errortype>sql-database-error</errortype></member>
200 <member><errortype>sql-error</errortype></member>
201 <member><errortype>error</errortype></member>
202 <member><errortype>serious-condition</errortype></member>
203 <member><errortype>sql-condition</errortype></member>
204 <member><errortype>condition</errortype></member>
205 <member><errortype>t</errortype></member>
210 <title>Description</title>
211 <para>This condition represents errors that occur while
212 executing SQL statements, either as part of query operations
213 or command execution, either explicitly or implicitly, as
214 caused e.g. by <function>with-transaction</function>.
215 The following initialization arguments and accessors exist:</para>
217 <segtitle>Initarg</segtitle>
218 <segtitle>Accessor</segtitle>
219 <segtitle>Description</segtitle>
221 <seg><symbol>:database</symbol></seg>
222 <seg><function>sql-database-error-database</function></seg>
223 <seg>The database object that was involved in the
227 <seg><symbol>:expression</symbol></seg>
228 <seg><function>sql-database-error-expression</function></seg>
229 <seg>The SQL expression whose execution caused the error.</seg>
232 <seg><symbol>:errno</symbol></seg>
233 <seg><function>sql-database-error-errno</function></seg>
234 <seg>The numeric or symbolic error specification
235 returned by the database back-end. The values and
236 semantics of this are interface specific.</seg>
239 <seg><symbol>:error</symbol></seg>
240 <seg><function>sql-database-error-error</function></seg>
241 <seg>A string describing the problem that occurred,
242 possibly one returned by the database back-end.</seg>
248 <!-- Database Types -->
249 <refentry id="default-database-type">
251 <refname>*DEFAULT-DATABASE-TYPE*</refname>
252 <refpurpose>The default database type to use</refpurpose>
253 <refclass>Variable</refclass>
256 <title>Value Type</title>
257 <para>Any keyword representing a valid database back-end of
259 <symbol>nil</symbol>.</para>
262 <title>Initial Value</title>
263 <para><symbol>nil</symbol></para>
266 <title>Description</title>
267 <para>The value of this variable is used in calls to
268 <function>initialize-database-type</function> and
269 <function>connect</function> as the default
270 value of the <parameter>database-type</parameter>
273 <para>If the value of this variable is <symbol>nil</symbol>,
275 <function>initialize-database-type</function> or
276 <function>connect</function> will have to specify the
277 <parameter>database-type</parameter> to use, or a
278 general-purpose error will be signalled.</para>
282 <title>Examples</title>
284 (setf *default-database-type* :mysql)
286 (initialize-database-type)
291 <title>Affected By</title>
295 <title>See Also</title>
303 <refentry id="initialized-database-types">
305 <refname>*INITIALIZED-DATABASE-TYPES*</refname>
306 <refpurpose>List of all initialized database types</refpurpose>
307 <refclass>Variable</refclass>
310 <title>Value Type</title>
311 <para>A list of all initialized database types, each of which
312 represented by it's corresponding keyword.</para>
315 <title>Initial Value</title>
316 <para><symbol>nil</symbol></para>
319 <title>Description</title>
320 <para>This variable is updated whenever
321 <function>initialize-database-type</function> is called for a
322 database type which hasn't already been initialized before,
323 as determined by this variable. In that case the keyword
324 representing the database type is pushed onto the list
326 <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
328 <para>Attempts to modify the value of this variable will
329 result in undefined behaviour.</para>
333 <title>Examples</title>
335 (setf *default-database-type* :mysql)
337 (initialize-database-type)
339 *initialized-database-types*
344 <title>Affected By</title>
347 <member><function>initialize-database-type</function></member>
352 <title>See Also</title>
357 <para>Direct access to this variable is primarily provided
358 because of compatibility with Harlequin's <application>Common
359 SQL</application>.</para>
362 <refentry id="initialize-database-type">
364 <refname>INITIALIZE-DATABASE-TYPE</refname>
365 <refpurpose>Initializes a database type</refpurpose>
366 <refclass>Function</refclass>
369 <title>Syntax</title>
370 <synopsis><function>initialize-database-type</function> &key <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
373 <title>Arguments and Values</title>
376 <term><parameter>database-type</parameter></term>
378 <para>The database type to initialize, i.e. a keyword
379 symbol denoting a known database back-end. Defaults to
381 <symbol>*default-database-type*</symbol>.</para>
385 <term><returnvalue>result</returnvalue></term>
387 <para>Either <symbol>nil</symbol> if the initialization
388 attempt fails, or <symbol>t</symbol> otherwise.</para>
394 <title>Description</title>
395 <para>If the back-end specified by
396 <parameter>database-type</parameter> has not already been
397 initialized, as seen from
398 <symbol>*initialized-database-types*</symbol>, an attempt is
399 made to initialize the database. If this attempt succeeds,
400 or the back-end has already been initialized, the function
401 returns t, and places the keyword denoting the database type
402 onto the list stored in
403 <symbol>*initialized-database-types*</symbol>, if not
404 already present.</para>
405 <para>If initialization fails, the function returns
406 <symbol>nil</symbol>, and/or signals an error of type
407 <errortype>clsql-error</errortype>. The kind of action
408 taken depends on the back-end and the cause of the
412 <title>Examples</title>
414 *initialized-database-types*
416 (setf *default-database-type* :mysql)
418 (initialize-database-type)
419 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
420 >> Compiling Top-Level Form:
423 *initialized-database-types*
425 (initialize-database-type)
427 *initialized-database-types*
432 <title>Side Effects</title>
433 <para>The database back-end corresponding to the database type
434 specified is initialized, unless it has already been
435 initialized. This can involve any number of other side
436 effects, as determined by the back-end implementation (like
437 e.g. loading of foreign code, calling of foreign code,
438 networking operations, etc.). If initialization is
439 attempted and succeeds, the
440 <parameter>database-type</parameter> is pushed onto the list
442 <symbol>*initialized-database-types*</symbol>.</para>
445 <title>Affected by</title>
448 <member><symbol>*default-database-type*</symbol></member>
449 <member><symbol>*initialized-database-types*</symbol></member>
454 <title>Exceptional Situations</title>
455 <para>If an error is encountered during the initialization
456 attempt, the back-end may signal errors of kind
457 <errortype>clsql-error</errortype>.</para>
460 <title>See Also</title>
468 <!-- Databases Connection and Disconnection -->
469 <refentry id="connect-if-exists">
471 <refname>*CONNECT-IF-EXISTS*</refname>
472 <refpurpose>Default value for the
473 <parameter>if-exists</parameter> parameter of
474 <function>connect</function>.</refpurpose>
475 <refclass>Variable</refclass>
478 <title>Value Type</title>
479 <para>A valid argument to the <parameter>if-exists</parameter>
480 parameter of <function>connect</function>, i.e. one of
481 <simplelist type="inline">
482 <member><symbol>:new</symbol></member>
483 <member><symbol>:warn-new</symbol></member>
484 <member><symbol>:error</symbol></member>
485 <member><symbol>:warn-old</symbol></member>
486 <member><symbol>:old</symbol></member>
491 <title>Initial Value</title>
492 <para><symbol>:error</symbol></para>
495 <title>Description</title>
496 <para>The value of this variable is used in calls to
497 <function>connect</function> as the default
498 value of the <parameter>if-exists</parameter>
500 linkend="connect"><function>connect</function></link> for
501 the semantics of the valid values for this variable.</para>
504 <title>Examples</title>
508 <title>Affected By</title>
512 <title>See Also</title>
516 linkend="connect"><function>connect</function></link></member>
525 <refentry id="connected-databases">
527 <refname>CONNECTED-DATABASES</refname>
528 <refpurpose>Return the list of active database
529 objects.</refpurpose>
530 <refclass>Function</refclass>
533 <title>Syntax</title>
534 <synopsis><function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
537 <title>Arguments and Values</title>
540 <term><returnvalue>databases</returnvalue></term>
542 <para>The list of active database objects.</para>
548 <title>Description</title>
549 <para>This function returns the list of active database
550 objects, i.e. all those database objects created by calls to
551 <function>connect</function>, which have not been closed by
552 calling <function>disconnect</function> on them.</para>
554 <para>The consequences of modifying the list returned by
555 <function>connected-databases</function> are
560 <title>Examples</title>
562 (connected-databases)
564 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
565 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
566 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
567 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
568 (connected-databases)
569 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
570 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
573 (connected-databases)
574 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
577 (connected-databases)
582 <title>Side Effects</title>
586 <title>Affected By</title>
589 <member><function>connect</function></member>
590 <member><function>disconnect</function></member>
595 <title>Exceptional Situations</title>
599 <title>See Also</title>
607 <refentry id="default-database">
609 <refname>*DEFAULT-DATABASE*</refname>
610 <refpurpose>The default database object to use</refpurpose>
611 <refclass>Variable</refclass>
614 <title>Value Type</title>
615 <para>Any object of type <type>database</type>, or nil to
616 indicate no default database.</para>
619 <title>Initial Value</title>
620 <para><symbol>nil</symbol></para>
623 <title>Description</title>
624 <para>Any function or macro in
625 &clsql; that operates on a
626 database uses the value of this variable as the default
627 value for it's <parameter>database</parameter>
629 <para>The value of this parameter is changed by calls to
630 <function>connect</function>, which sets
631 <symbol>*default-database*</symbol> to the database object
632 it returns. It is also changed by calls to
633 <function>disconnect</function>, when the database object
634 being disconnected is the same as the value of
635 <symbol>*default-database*</symbol>. In this case
636 <function>disconnect</function> sets
637 <symbol>*default-database*</symbol> to the first database
638 that remains in the list of active databases as returned by
639 <function>connected-databases</function>, or
640 <symbol>nil</symbol> if no further active databases
642 <para>The user may change <symbol>*default-database*</symbol>
643 at any time to a valid value of his choice.</para>
645 <para>If the value of <symbol>*default-database*</symbol> is
646 <symbol>nil</symbol>, then all calls to
647 &clsql; functions on databases
648 must provide a suitable <parameter>database</parameter>
649 parameter, or an error will be signalled.</para>
653 <title>Examples</title>
655 (connected-databases)
657 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
658 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
659 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
660 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
661 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
662 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
664 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
668 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
672 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
677 (connected-databases)
682 <title>Affected By</title>
685 <member><link linkend="connect"><function>connect</function></link></member>
686 <member><link linkend="disconnect"><function>disconnect</function></link></member>
691 <title>See Also</title>
694 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
701 <para>This variable is intended to facilitate working with
702 &clsql; in an interactive
703 fashion at the top-level loop, and because of this,
704 <function>connect</function> and
705 <function>disconnect</function> provide some fairly
706 complex behaviour to keep
707 <symbol>*default-database*</symbol> set to useful values.
708 Programmatic use of &clsql;
709 should never depend on the value of
710 <symbol>*default-database*</symbol> and should provide
711 correct database objects via the
712 <parameter>database</parameter> parameter to functions
718 <refentry id="database">
720 <refname>DATABASE</refname>
721 <refpurpose>The super-type of all
722 &clsql; databases</refpurpose>
723 <refclass>Class</refclass>
726 <title>Class Precedence List</title>
728 <simplelist type="inline">
729 <member><type>database</type></member>
730 <member><type>standard-object</type></member>
731 <member><type>t</type></member>
736 <title>Description</title>
737 <para>This class is the superclass of all
738 &clsql; databases. The different
739 database back-ends derive subclasses of this class to
740 implement their databases. No instances of this class are
741 ever created by &clsql;.</para>
744 <refentry id="closed-database">
746 <refname>CLOSED-DATABASE</refname>
747 <refpurpose>The class representing all closed
748 &clsql; databases</refpurpose>
749 <refclass>Class</refclass>
752 <title>Class Precedence List</title>
754 <simplelist type="inline">
755 <member><type>closed-database</type></member>
756 <member><type>standard-object</type></member>
757 <member><type>t</type></member>
762 <title>Description</title>
763 <para>&clsql; <type>database</type>
764 instances are changed to this class via
765 <function>change-class</function> after they are closed via
766 <function>disconnect</function>. All functions and generic
767 functions that take database objects as arguments will
768 signal errors of type
769 <errortype>clsql-closed-error</errortype> when they are
770 called on instances of <type>closed-database</type>, with
771 the exception of <function>database-name</function>, which
772 will continue to work as for instances of
773 <type>database</type>.</para>
777 <refentry id="database-name">
779 <refname>DATABASE-NAME</refname>
780 <refpurpose>Get the name of a database object</refpurpose>
781 <refclass>Generic Function</refclass>
784 <title>Syntax</title>
785 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
788 <title>Arguments and Values</title>
791 <term><parameter>database</parameter></term>
793 <para>A database object, either of type
794 <type>database</type> or of type
795 <type>closed-database</type>.</para>
799 <term><returnvalue>name</returnvalue></term>
801 <para>A string describing the identity of the database
802 to which this database object is connected to.</para>
808 <title>Description</title>
809 <para>This function returns the database name of the given
810 database. The database name is a string which somehow
811 describes the identity of the database to which this
812 database object is or has been connected. The database name
813 of a database object is determined at
814 <function>connect</function> time, when a call to
815 <function>database-name-from-spec</function> derives the
816 database name from the connection specification passed to
817 <function>connect</function> in the
818 <parameter>connection-spec</parameter> parameter.</para>
819 <para>The database name is used via
820 <function>find-database</function> in
821 <function>connect</function> to determine whether database
822 connections to the specified database exist already.</para>
823 <para>Usually the database name string will include
824 indications of the host, database name, user, or port that
825 where used during the connection attempt. The only
826 important thing is that this string shall try to identify
827 the database at the other end of the connection. Connection
828 specifications parts like passwords and credentials shall
829 not be used as part of the database name.</para>
832 <title>Examples</title>
834 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
835 => "dent/newesim/dent"
836 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
837 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
838 (database-name *default-database*)
839 => "dent/newesim/dent"
841 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
843 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
844 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
845 (database-name *default-database*)
848 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
849 => "www.pmsf.de/template1/dent"
853 <title>Side Effects</title>
857 <title>Affected By</title>
860 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
865 <title>Exceptional Situations</title>
866 <para>Will signal an error if the object passed as the
867 <parameter>database</parameter> parameter is neither of type
868 <type>database</type> nor of type
869 <type>closed-database</type>.</para>
872 <title>See Also</title>
876 linkend="connect"><function>connect</function></link></member>
878 linkend="find-database"><function>find-database</function></link></member>
887 <refentry id="find-database">
889 <refname>FIND-DATABASE</refname>
890 <refpurpose>Locate a database object through it's
892 <refclass>Function</refclass>
895 <title>Syntax</title>
896 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
899 <title>Arguments and Values</title>
902 <term><parameter>database</parameter></term>
904 <para>A database object or a string, denoting a database
909 <term><parameter>errorp</parameter></term>
911 <para>A generalized boolean. Defaults to
912 <symbol>t</symbol>.</para>
916 <term><returnvalue>result</returnvalue></term>
918 <para>Either a database object, or, if
919 <parameter>errorp</parameter> is <symbol>nil</symbol>,
920 possibly <symbol>nil</symbol>.</para>
926 <title>Description</title>
927 <para><function>find-database</function> locates an active
928 database object given the specification in
929 <parameter>database</parameter>. If
930 <parameter>database</parameter> is an object of type
931 <type>database</type>, <function>find-database</function>
932 returns this. Otherwise it will search the active databases
933 as indicated by the list returned by
934 <function>connected-databases</function> for a database
935 whose name (as returned by
936 <function>database-name</function> is equal as per
937 <function>string=</function> to the string passed as
938 <parameter>database</parameter>. If it succeeds, it returns
939 the first database found.</para>
940 <para>If it fails to find a matching database, it will signal
941 an error of type <errortype>clsql-error</errortype> if
942 <parameter>errorp</parameter> is true. If
943 <parameter>errorp</parameter> is <symbol>nil</symbol>, it
944 will return <symbol>nil</symbol> instead.</para>
947 <title>Examples</title>
949 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
950 => "dent/newesim/dent"
951 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
952 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
953 (database-name *default-database*)
954 => "dent/newesim/dent"
956 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
958 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
959 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
960 (database-name *default-database*)
963 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
964 => "www.pmsf.de/template1/dent"
966 (find-database "dent/newesim/dent")
967 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
968 (find-database "/template1/dent")
969 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
970 (find-database "www.pmsf.de/template1/dent" nil)
973 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
977 <title>Side Effects</title>
981 <title>Affected By</title>
984 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
989 <title>Exceptional Situations</title>
990 <para>Will signal an error of type
991 <errortype>clsql-error</errortype> if no matching database
992 can be found, and <parameter>errorp</parameter> is true.
993 Will signal an error if the value of
994 <parameter>database</parameter> is neither an object of type
995 <type>database</type> nor a string.</para>
998 <title>See Also</title>
1002 linkend="database-name"><function>database-name</function></link></member>
1004 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1009 <title>Notes</title>
1014 <refentry id="connect">
1016 <refname>CONNECT</refname>
1017 <refpurpose>create a connection to a database</refpurpose>
1018 <refclass>Function</refclass>
1021 <title>Syntax</title>
1022 <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> => <returnvalue>database</returnvalue></synopsis>
1025 <title>Arguments and Values</title>
1028 <term><parameter>connection-spec</parameter></term>
1030 <para>A connection specification</para>
1034 <term><parameter>if-exists</parameter></term>
1036 <para>This indicates the action to take if a connection
1037 to the same database exists already. See below for the
1038 legal values and actions. It defaults to the value of
1039 <symbol>*connect-if-exists*</symbol>.</para>
1043 <term><parameter>database-type</parameter></term>
1045 <para>A database type specifier, i.e. a keyword.
1046 This defaults to the value of
1047 <symbol>*default-database-type*</symbol></para>
1051 <term><parameter>pool</parameter></term>
1053 <para>A boolean flag. If &t;, acquire connection from a
1054 pool of open connections. If the pool is empty, a new
1055 connection is created. The default is &nil;.
1060 <term><returnvalue>database</returnvalue></term>
1062 <para>The database object representing the connection.</para>
1068 <title>Description</title>
1069 <para>This function takes a connection specification and
1070 a database type and creates a connection to the database
1071 specified by those. The type and structure of the
1072 connection specification depend on the database type.</para>
1073 <para>The parameter <parameter>if-exists</parameter> specifies
1074 what to do if a connection to the database specified exists
1075 already, which is checked by calling
1076 <function>find-database</function> on the database name
1077 returned by <function>database-name-from-spec</function>
1078 when called with the <parameter>connection-spec</parameter>
1079 and <parameter>database-type</parameter> parameters. The
1080 possible values of <parameter>if-exists</parameter> are:
1083 <term><symbol>:new</symbol></term>
1085 <para>Go ahead and create a new connection.</para>
1089 <term><symbol>:warn-new</symbol></term>
1091 <para>This is just like <symbol>:new</symbol>, but
1092 also signals a warning of type
1093 <errortype>clsql-exists-warning</errortype>,
1094 indicating the old and newly created
1099 <term><symbol>:error</symbol></term>
1101 <para>This will cause <function>connect</function> to
1102 signal a correctable error of type
1103 <errortype>clsql-exists-error</errortype>. The
1104 user may choose to proceed, either by indicating
1105 that a new connection shall be created, via the
1106 restart <symbol>create-new</symbol>, or by
1107 indicating that the existing connection shall be
1108 used, via the restart
1109 <symbol>use-old</symbol>.</para>
1113 <term><symbol>:old</symbol></term>
1115 <para>This will cause <function>connect</function> to
1116 use an old connection if one exists.</para>
1120 <term><symbol>:warn-old</symbol></term>
1122 <para>This is just like <symbol>:old</symbol>, but
1123 also signals a warning of type
1124 <errortype>clsql-exists-warning</errortype>,
1125 indicating the old database used, via the slots
1126 <symbol>old-db</symbol> and
1127 <symbol>new-db</symbol></para>
1132 <para>The database name of the returned database object will
1133 be the same under <function>string=</function> as that which
1134 would be returned by a call to
1135 <function>database-name-from-spec</function> with the given
1136 <parameter>connection-spec</parameter> and
1137 <parameter>database-type</parameter> parameters.</para>
1140 <title>Examples</title>
1142 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1143 => "dent/newesim/dent"
1144 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1145 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
1147 => "dent/newesim/dent"
1149 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1150 >> In call to CONNECT:
1151 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
1154 >> 0: [CREATE-NEW] Create a new connection.
1155 >> 1: [USE-OLD ] Use the existing connection.
1156 >> 2: [ABORT ] Return to Top-Level.
1158 >> Debug (type H for help)
1160 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
1162 >> ; File: /prj/CLSQL/sql/sql.cl
1163 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
1164 >> (CREATE-NEW NIL :REPORT "Create a new connection."
1166 >> (USE-OLD NIL :REPORT "Use the existing connection."
1167 >> (SETQ RESULT OLD-DB)))
1169 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
1173 <title>Side Effects</title>
1174 <para>A database connection is established, and the resultant
1175 database object is registered, so as to appear in the list
1176 returned by <function>connected-databases</function>.</para>
1179 <title>Affected by</title>
1182 <member><symbol>*default-database-type*</symbol></member>
1183 <member><symbol>*connect-if-exists*</symbol></member>
1188 <title>Exceptional Situations</title>
1189 <para>If the connection specification is not syntactically or
1190 semantically correct for the given database type, an error
1191 of type <errortype>clsql-invalid-spec-error</errortype> is
1192 signalled. If during the connection attempt an error is
1193 detected (e.g. because of permission problems, network
1194 trouble or any other cause), an error of type
1195 <errortype>sql-connection-error</errortype> is
1197 <para>If a connection to the database specified by
1198 <parameter>connection-spec</parameter> exists already,
1199 conditions are signalled according to the
1200 <parameter>if-exists</parameter> parameter, as described
1204 <title>See Also</title>
1207 <member><function>connected-databases</function></member>
1208 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1213 <title>Notes</title>
1218 <refentry id="disconnect">
1220 <refname>DISCONNECT</refname>
1221 <refpurpose>close a database connection</refpurpose>
1222 <refclass>Function</refclass>
1225 <title>Syntax</title>
1226 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>pool</replaceable> => <returnvalue>t</returnvalue></synopsis>
1229 <title>Arguments and Values</title>
1232 <term><parameter>pool</parameter></term>
1234 <para>A boolean flag indicating whether to put the database into a
1235 pool of opened databases. If &t;, rather than terminating the database connection, the
1236 connection is left open and the connection is placed into a pool of connections. Subsequent
1237 calls to <link linkend="connect"><function>connect</function></link> can then reuse this connection.
1238 The default is &nil;.
1243 <term><parameter>database</parameter></term>
1245 <para>The database to disconnect, which defaults to the
1246 database indicated by
1247 <symbol>*default-database*</symbol>.</para>
1253 <title>Description</title>
1254 <para>This function takes a <type>database</type> object as
1255 returned by <function>connect</function>, and closes the
1256 connection. The class of the object passed is changed to
1257 <type>closed-database</type> after the disconnection
1258 succeeds, thereby preventing further use of the object as
1259 an argument to &clsql; functions,
1260 with the exception of <function>database-name</function>.
1261 If the user does pass a closed database object to any other
1262 &clsql; function, an error of type
1263 <errortype>clsql-closed-error</errortype> is
1267 <title>Examples</title>
1269 (disconnect :database (find-database "dent/newesim/dent"))
1274 <title>Side Effects</title>
1275 <para>The database connection is closed, and the database
1276 object is removed from the list of connected databases as
1277 returned by <function>connected-databases</function>.</para>
1278 <para>The class of the database object is changed to
1279 <type>closed-database</type>.</para>
1280 <para>If the database object passed is the same under
1281 <function>eq</function> as the value of
1282 <symbol>*default-database*</symbol>, then
1283 <symbol>*default-database*</symbol> is set to the first
1284 remaining database from
1285 <function>connected-databases</function> or to nil if no
1286 further active database exists.</para>
1289 <title>Affected by</title>
1292 <member><symbol>*default-database*</symbol></member>
1297 <title>Exceptional Situations</title>
1298 <para>If during the disconnection attempt an error is
1299 detected (e.g. because of network trouble or any other
1300 cause), an error of type <errortype>clsql-error</errortype>
1301 might be signalled.</para>
1304 <title>See Also</title>
1307 <member><link linkend="connect"><function>connect</function></link></member>
1308 <member><link linkend="connect"><function>closed-database</function></link></member>
1313 <title>Notes</title>
1318 <refentry id="disconnect-pooled">
1320 <refname>DISCONNECT-POOLED</refname>
1321 <refpurpose>closes all pooled database connections</refpurpose>
1322 <refclass>Function</refclass>
1325 <title>Syntax</title>
1326 <synopsis><function>disconnect-pool</function> => <returnvalue>t</returnvalue></synopsis>
1329 <title>Description</title>
1330 <para>This function disconnects all database connections
1331 that have been placed into the pool. Connections are placed
1332 in the pool by calling <link
1333 linkend="disconnect"><function>disconnection</function></link>.
1337 <title>Examples</title>
1344 <title>Side Effects</title>
1345 <para>Database connections will be closed and entries in the pool are removed.
1349 <title>Affected by</title>
1352 <member><function>disconnect</function></member>
1357 <title>Exceptional Situations</title>
1358 <para>If during the disconnection attempt an error is
1359 detected (e.g. because of network trouble or any other
1360 cause), an error of type <errortype>clsql-error</errortype>
1361 might be signalled.</para>
1364 <title>See Also</title>
1367 <member><link linkend="connect"><function>connect</function></link></member>
1368 <member><link linkend="connect"><function>closed-database</function></link></member>
1373 <title>Notes</title>
1378 <refentry id="create_db">
1380 <refname>CREATE-DATABASE</refname>
1381 <refpurpose>create a database</refpurpose>
1382 <refclass>Function</refclass>
1385 <title>Syntax</title>
1386 <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1389 <title>Arguments and Values</title>
1392 <term><parameter>connection-spec</parameter></term>
1394 <para>A connection specification</para>
1398 <term><parameter>database-type</parameter></term>
1400 <para>A database type specifier, i.e. a keyword.
1401 This defaults to the value of
1402 <symbol>*default-database-type*</symbol></para>
1406 <term><parameter>success</parameter></term>
1408 <para>A boolean flag. If &t;, a new database was
1409 successfully created.
1416 <title>Description</title>
1417 <para>This function creates a database in the database system
1418 specified by <parameter>database-type</parameter>.
1422 <title>Examples</title>
1424 (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
1427 (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
1429 Error: While trying to access database localhost/new/dent
1430 using database-type MYSQL:
1431 Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1432 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1434 [condition type: CLSQL-ACCESS-ERROR]
1438 <title>Side Effects</title>
1439 <para>A database will be created on the filesystem of the host.</para>
1442 <title>Exceptional Situations</title>
1443 <para>An exception will be thrown if the database system does
1444 not allow new databases to be created or if database creation
1448 <title>Notes</title>
1449 <para>This function may invoke the operating systems
1450 functions. Thus, some database systems may require the
1451 administration functions to be available in the current
1452 <symbol>PATH</symbol>. At this time, the
1453 <symbol>:mysql</symbol> backend requires
1454 <filename>mysqladmin</filename> and the
1455 <symbol>:postgresql</symbol> backend requires
1456 <filename>createdb</filename>.</para>
1460 <refentry id="destroy_db">
1462 <refname>DESTROY-DATABASE</refname>
1463 <refpurpose>destroys a database</refpurpose>
1464 <refclass>Function</refclass>
1467 <title>Syntax</title>
1468 <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1471 <title>Arguments and Values</title>
1474 <term><parameter>connection-spec</parameter></term>
1476 <para>A connection specification</para>
1480 <term><parameter>database-type</parameter></term>
1482 <para>A database type specifier, i.e. a keyword.
1483 This defaults to the value of
1484 <symbol>*default-database-type*</symbol></para>
1488 <term><parameter>success</parameter></term>
1490 <para>A boolean flag. If &t;, the database was
1491 successfully destroyed.
1498 <title>Description</title>
1499 <para>This function destroy a database in the database system
1500 specified by <parameter>database-type</parameter>.
1504 <title>Examples</title>
1506 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1509 (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1511 Error: While trying to access database localhost/test2/root
1512 using database-type POSTGRESQL:
1513 Error database-destory failed: dropdb: database removal failed: ERROR: database "test2" does not exist
1515 [condition type: CLSQL-ACCESS-ERROR]
1519 <title>Side Effects</title>
1520 <para>A database will be removed from the filesystem of the host.</para>
1523 <title>Exceptional Situations</title>
1524 <para>An exception will be thrown if the database system does not
1525 allow databases to be removed, the database does not exist, or
1526 if database removal fails.</para>
1529 <title>Notes</title>
1530 <para>This function may invoke the operating systems
1531 functions. Thus, some database systems may require the
1532 administration functions to be available in the current
1533 <symbol>PATH</symbol>. At this time, the
1534 <symbol>:mysql</symbol> backend requires
1535 <filename>mysqladmin</filename> and the
1536 <symbol>:postgresql</symbol> backend requires
1537 <filename>dropdb</filename>.</para>
1541 <refentry id="probe_db">
1543 <refname>PROBE-DATABASE</refname>
1544 <refpurpose>tests for existence of a database</refpurpose>
1545 <refclass>Function</refclass>
1548 <title>Syntax</title>
1549 <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1552 <title>Arguments and Values</title>
1555 <term><parameter>connection-spec</parameter></term>
1557 <para>A connection specification</para>
1561 <term><parameter>database-type</parameter></term>
1563 <para>A database type specifier, i.e. a keyword.
1564 This defaults to the value of
1565 <symbol>*default-database-type*</symbol></para>
1569 <term><parameter>success</parameter></term>
1571 <para>A boolean flag. If &t;, the database exists
1572 in the database system.
1579 <title>Description</title>
1580 <para>This function tests for the existence of a database in
1581 the database system specified by
1582 <parameter>database-type</parameter>.
1586 <title>Examples</title>
1588 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1593 <title>Side Effects</title>
1597 <title>Exceptional Situations</title>
1598 <para>An exception maybe thrown if the database system does
1599 not receive administrator-level authentication since function
1600 may need to read the administrative database of the database
1604 <title>Notes</title>
1609 <refentry id="database-name-from-spec">
1611 <refname>DATABASE-NAME-FROM-SPEC</refname>
1612 <refpurpose>Return the database name string corresponding to
1613 the given connection specification.</refpurpose>
1614 <refclass>Generic Function</refclass>
1617 <title>Syntax</title>
1619 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
1622 <title>Arguments and Values</title>
1625 <term><parameter>connection-spec</parameter></term>
1627 <para>A connection specification, whose structure and
1628 interpretation are dependent on the
1629 <parameter>database-type</parameter>.</para>
1633 <term><parameter>database-type</parameter></term>
1635 <para>A database type specifier, i.e. a keyword.</para>
1639 <term><returnvalue>name</returnvalue></term>
1641 <para>A string denoting a database name.</para>
1647 <title>Description</title>
1648 <para>This generic function takes a connection specification
1649 and a database type and returns the database name of the
1650 database object that would be created had
1651 <function>connect</function> been called with the given
1652 connection specification and database types.</para>
1653 <para>This function is useful in determining a database name
1654 from the connection specification, since the way the
1655 connection specification is converted into a database name
1656 is dependent on the database type.</para>
1659 <title>Examples</title>
1661 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1662 => "dent/newesim/dent"
1663 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1664 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1665 (database-name *default-database*)
1666 => "dent/newesim/dent"
1668 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1669 => "/template1/dent"
1670 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1671 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1672 (database-name *default-database*)
1673 => "/template1/dent"
1675 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1676 => "www.pmsf.de/template1/dent"
1678 (find-database "dent/newesim/dent")
1679 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1680 (find-database "/template1/dent")
1681 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1682 (find-database "www.pmsf.de/template1/dent" nil)
1685 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1689 <title>Side Effects</title>
1693 <title>Affected by</title>
1697 <title>Exceptional Situations</title>
1698 <para>If the value of <parameter>connection-spec</parameter>
1699 is not a valid connection specification for the given
1700 database type, an error of type
1701 <errortype>clsql-invalid-spec-error</errortype> might be
1705 <title>See Also</title>
1708 <member><link linkend="connect"><function>connect</function></link></member>
1713 <title>Notes</title>
1717 <!-- Querying Operations -->
1718 <refentry id="execute-command">
1720 <refname>EXECUTE-COMMAND</refname>
1721 <refpurpose>Execute an SQL command which returns no
1722 values.</refpurpose>
1723 <refclass>Function</refclass>
1726 <title>Syntax</title>
1727 <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1730 <title>Arguments and Values</title>
1733 <term><parameter>sql-expression</parameter></term>
1735 <para>An <glossterm linkend="gloss-sql-expression">sql
1736 expression</glossterm> that represents an SQL
1737 statement which will return no values.</para>
1741 <term><parameter>database</parameter></term>
1744 <glossterm linkend="gloss-database-object">database
1745 object</glossterm>. This will default to the value
1746 of <symbol>*default-database*</symbol>.</para>
1752 <title>Description</title>
1753 <para>This will execute the command given by
1754 <parameter>sql-expression</parameter> in the
1755 <parameter>database</parameter> specified. If the execution
1756 succeeds it will return <symbol>t</symbol>, otherwise an
1757 error of type <errortype>sql-database-error</errortype> will
1758 be signalled.</para>
1761 <title>Examples</title>
1763 (execute-command "create table eventlog (time char(30),event char(70))")
1766 (execute-command "create table eventlog (time char(30),event char(70))")
1768 >> While accessing database #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
1769 >> with expression "create table eventlog (time char(30),event char(70))":
1770 >> Error NIL: ERROR: amcreate: eventlog relation already exists
1774 >> 0: [ABORT] Return to Top-Level.
1776 >> Debug (type H for help)
1778 >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
1781 >> #<unavailable-arg>
1782 >> #<unavailable-arg>)
1783 >> Source: (ERROR 'SQL-DATABASE-ERROR :DATABASE DATABASE :EXPRESSION ...)
1786 (execute-command "drop table eventlog")
1791 <title>Side Effects</title>
1792 <para>Whatever effects the execution of the SQL statement has
1793 on the underlying database, if any.</para>
1796 <title>Affected by</title>
1800 <title>Exceptional Situations</title>
1801 <para>If the execution of the SQL statement leads to any
1802 errors, an error of type
1803 <errortype>sql-database-error</errortype> is signalled.</para>
1806 <title>See Also</title>
1809 <member><link linkend="query"><function>query</function></link></member>
1814 <title>Notes</title>
1818 <refentry id="query">
1820 <refname>QUERY</refname>
1821 <refpurpose>Execute an SQL query and return the tuples as a
1823 <refclass>Function</refclass>
1826 <title>Syntax</title>
1827 <synopsis><function>query</function> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> => <returnvalue>result</returnvalue></synopsis>
1830 <title>Arguments and Values</title>
1833 <term><parameter>query-expression</parameter></term>
1835 <para>An <glossterm linkend="gloss-sql-expression">sql
1836 expression</glossterm> that represents an SQL
1837 query which is expected to return a (possibly empty)
1842 <term><parameter>database</parameter></term>
1845 <glossterm linkend="gloss-database-object">database
1846 object</glossterm>. This will default to the value
1847 of <symbol>*default-database*</symbol>.</para>
1851 <term><parameter>result-types</parameter></term>
1854 <glossterm linkend="gloss-field-types">field type
1855 specifier</glossterm>. The default is &nil;.
1858 The purpose of this argument is cause &clsql; to
1859 import SQL numeric fields into numeric Lisp objects
1860 rather than strings. This reduces the cost of
1861 allocating a temporary string and the &clsql; users'
1862 inconvenience of converting number strings into number
1866 A value of <symbol>:auto</symbol> causes &clsql;
1867 to automatically convert SQL fields into a
1868 numeric format where applicable. The default value of
1869 &nil; causes all fields to be returned as strings
1870 regardless of the SQL type. Otherwise a list is expected
1871 which has a element for each field that specifies the
1872 conversion. If the list is shorter than the number
1873 of fields, the a value of <symbol>t</symbol> is
1874 assumed for the field. If the list is longer than
1875 the number of fields, the extra elements are
1877 <simplelist type="vert">
1878 <member><symbol>:int</symbol> Field is imported as a
1879 signed integer, from 8-bits to 64-bits depending
1880 upon the field type.
1882 <member><symbol>:double</symbol> Field is imported as a
1883 double-float number.
1885 <member><symbol>t</symbol> Field is imported as a
1893 <term><parameter>field-names</parameter></term>
1896 A boolean with a default value of &t;. When &t;, this
1897 function results a second value of a list of field
1898 names. When &nil;, this function only returns one value
1904 <term><returnvalue>result</returnvalue></term>
1906 <para>A list representing the result set obtained. For
1907 each tuple in the result set, there is an element in
1908 this list, which is itself a list of all the attribute
1909 values in the tuple.</para>
1915 <title>Description</title>
1916 <para>This will execute the query given by
1917 <parameter>query-expression</parameter> in the
1918 <parameter>database</parameter> specified. If the execution
1919 succeeds it will return the result set returned by the
1920 database, otherwise an error of type
1921 <errortype>sql-database-error</errortype> will
1922 be signalled.</para>
1925 <title>Examples</title>
1927 (execute-command "create table simple (name char(50), salary numeric(10,2))")
1929 (execute-command "insert into simple values ('Mai, Pierre',10000)")
1931 (execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
1933 (query "select * from simple")
1934 => (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
1935 (query "select salary from simple")
1936 => (("10000.00") ("8000.50"))
1937 (query "select salary from simple where salary > 10000")
1939 (query "select salary,name from simple where salary > 10000")
1941 (query "select salary,name from simple where salary > 9000")
1942 => (("10000.00" "Mai, Pierre"))
1943 (query "select salary,name from simple where salary > 8000")
1944 => (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
1947 (query "show tables")
1948 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
1952 <title>Side Effects</title>
1953 <para>Whatever effects the execution of the SQL query has
1954 on the underlying database, if any.</para>
1957 <title>Affected by</title>
1961 <title>Exceptional Situations</title>
1962 <para>If the execution of the SQL query leads to any
1963 errors, an error of type
1964 <errortype>sql-database-error</errortype> is signalled.</para>
1967 <title>See Also</title>
1970 <member><link linkend="execute-command"><function>execute-command</function></link></member>
1975 <title>Notes</title>
1980 <refentry id="map-query">
1982 <refname>MAP-QUERY</refname>
1983 <refpurpose>Map a function over all the tuples from a
1985 <refclass>Function</refclass>
1988 <title>Syntax</title>
1989 <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>result-types</replaceable> => <returnvalue>result</returnvalue></synopsis>
1992 <title>Arguments and Values</title>
1995 <term><parameter>output-type-spec</parameter></term>
1997 <para>A sequence type specifier or <symbol>nil</symbol>.</para>
2001 <term><parameter>function</parameter></term>
2003 <para>A function designator.
2004 <parameter>function</parameter> takes a single argument which
2005 is the atom value for a query single with a single column
2006 or is a list of values for a multi-column query.</para>
2010 <term><parameter>query-expression</parameter></term>
2012 <para>An <glossterm linkend="gloss-sql-expression">sql
2013 expression</glossterm> that represents an SQL
2014 query which is expected to return a (possibly empty)
2019 <term><parameter>database</parameter></term>
2022 <glossterm linkend="gloss-database-object">database
2023 object</glossterm>. This will default to the value
2024 of <symbol>*default-database*</symbol>.</para>
2028 <term><parameter>result-types</parameter></term>
2031 A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
2032 The default is &nil;. See <link
2033 linkend="query"><function>query</function></link>
2034 for the semantics of this argument.
2039 <term><returnvalue>result</returnvalue></term>
2041 <para>If <parameter>output-type-spec</parameter> is a
2042 type specifier other than <symbol>nil</symbol>, then a
2043 sequence of the type it denotes. Otherwise
2044 <symbol>nil</symbol> is returned.</para>
2050 <title>Description</title>
2051 <para>Applies <parameter>function</parameter> to the
2052 successive tuples in the result set returned
2053 by executing the SQL
2054 <parameter>query-expression</parameter>. If the
2055 <parameter>output-type-spec</parameter> is
2056 <symbol>nil</symbol>, then the result of each application
2057 of <parameter>function</parameter> is discarded, and
2058 <function>map-query</function> returns
2059 <symbol>nil</symbol>. Otherwise the result of each
2060 successive application of <parameter>function</parameter> is
2061 collected in a sequence of type
2062 <parameter>output-type-spec</parameter>, where the jths
2063 element is the result of applying
2064 <parameter>function</parameter> to the attributes of the
2065 jths tuple in the result set. The collected sequence is the
2066 result of the call to <function>map-query</function>.
2068 <para>If the <parameter>output-type-spec</parameter> is a
2069 subtype of <type>list</type>, the result will be a
2070 <type>list</type>.</para>
2071 <para>If the <parameter>result-type</parameter> is a subtype
2072 of <type>vector</type>, then if the implementation can
2073 determine the element type specified for the
2074 <parameter>result-type</parameter>, the element type of the
2075 resulting array is the result of
2076 <emphasis>upgrading</emphasis> that element type; or, if the
2077 implementation can determine that the element type is
2078 unspecified (or <symbol>*</symbol>), the element type of the
2079 resulting array is <type>t</type>; otherwise, an error is
2083 <title>Examples</title>
2085 (map-query 'list #'(lambda (tuple)
2086 (multiple-value-bind (salary name) tuple
2087 (declare (ignorable name))
2088 (read-from-string salary)))
2089 "select salary,name from simple where salary > 8000")
2092 (map-query '(vector double-float)
2094 (multiple-value-bind (salary name) tuple
2095 (declare (ignorable name))
2096 (let ((*read-default-float-format* 'double-float))
2097 (coerce (read-from-string salary) 'double-float))
2098 "select salary,name from simple where salary > 8000")))
2099 => #(10000.0d0 8000.5d0)
2101 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
2104 (values (map-query nil #'(lambda (tuple)
2105 (multiple-value-bind (salary name) tuple
2106 (push (cons name (read-from-string salary)) list))
2107 "select salary,name from simple where salary > 8000")
2110 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
2114 <title>Side Effects</title>
2115 <para>Whatever effects the execution of the SQL query has
2116 on the underlying database, if any.</para>
2119 <title>Affected by</title>
2123 <title>Exceptional Situations</title>
2124 <para>If the execution of the SQL query leads to any
2125 errors, an error of type
2126 <errortype>sql-database-error</errortype> is signalled.</para>
2127 <para>An error of type <errortype>type-error</errortype> must
2128 be signaled if the <parameter>output-type-spec</parameter> is
2129 not a recognizable subtype of <type>list</type>, not a
2130 recognizable subtype of <type>vector</type>, and not
2131 <symbol>nil</symbol>.</para>
2132 <para>An error of type <errortype>type-error</errortype>
2133 should be signaled if
2134 <parameter>output-type-spec</parameter> specifies the number
2135 of elements and the size of the result set is different from
2139 <title>See Also</title>
2142 <member><link linkend="query"><function>query</function></link></member>
2143 <member><link linkend="do-query"><function>do-query</function></link></member>
2148 <title>Notes</title>
2152 <refentry id="do-query">
2154 <refname>DO-QUERY</refname>
2155 <refpurpose>Iterate over all the tuples of a
2157 <refclass>Macro</refclass>
2160 <title>Syntax</title>
2161 <synopsis><function>do-query</function> ((&rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>result-types</replaceable>) &body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
2164 <title>Arguments and Values</title>
2167 <term><parameter>args</parameter></term>
2169 <para>A list of variable names.</para>
2173 <term><parameter>query-expression</parameter></term>
2175 <para>An <glossterm linkend="gloss-sql-expression">sql
2176 expression</glossterm> that represents an SQL
2177 query which is expected to return a (possibly empty)
2178 result set, where each tuple has as many attributes as
2179 <parameter>function</parameter> takes arguments.</para>
2183 <term><parameter>database</parameter></term>
2186 <glossterm linkend="gloss-database-object">database
2187 object</glossterm>. This will default to
2188 <symbol>*default-database*</symbol>.</para>
2192 <term><parameter>result-types</parameter></term>
2195 A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
2196 The default is &nil;. See <link
2197 linkend="query"><function>query</function></link>
2198 for the semantics of this argument.
2203 <term><parameter>body</parameter></term>
2205 <para>A body of Lisp code, like in a
2206 <function>destructuring-bind</function> form.</para>
2212 <title>Description</title>
2213 <para>Executes the <parameter>body</parameter> of code
2214 repeatedly with the variable names in
2215 <parameter>args</parameter> bound to the attributes of each
2216 tuple in the result set returned by executing the SQL
2217 <parameter>query-expression</parameter> on the
2218 <parameter>database</parameter> specified.</para>
2219 <para>The body of code is executed in a block named
2220 <symbol>nil</symbol> which may be returned from prematurely
2221 via <function>return</function> or
2222 <function>return-from</function>. In this case the result
2223 of evaluating the <function>do-query</function> form will be
2224 the one supplied to <function>return</function> or
2225 <function>return-from</function>. Otherwise the result will
2226 be <symbol>nil</symbol>.</para>
2227 <para>The body of code appears also is if wrapped in a
2228 <function>destructuring-bind</function> form, thus allowing
2229 declarations at the start of the body, especially those
2230 pertaining to the bindings of the variables named in
2231 <parameter>args</parameter>.</para>
2234 <title>Examples</title>
2236 (do-query ((salary name) "select salary,name from simple")
2237 (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
2238 >> Mai, Pierre gets $10000.00
2239 >> Hacker, Random J. gets $08000.50
2242 (do-query ((salary name) "select salary,name from simple")
2243 (return (cons salary name)))
2244 => ("10000.00" . "Mai, Pierre")
2248 <title>Side Effects</title>
2249 <para>Whatever effects the execution of the SQL query has
2250 on the underlying database, if any.</para>
2253 <title>Affected by</title>
2257 <title>Exceptional Situations</title>
2258 <para>If the execution of the SQL query leads to any
2259 errors, an error of type
2260 <errortype>sql-database-error</errortype> is signalled.</para>
2261 <para>If the number of variable names in
2262 <parameter>args</parameter> and the number of attributes in
2263 the tuples in the result set don't match up, an error is
2267 <title>See Also</title>
2270 <member><link linkend="query"><function>query</function></link></member>
2271 <member><link linkend="map-query"><function>map-query</function></link></member>
2276 <title>Notes</title>
2280 <refentry id="loop-tuples">
2282 <refname>LOOP-FOR-AS-TUPLES</refname>
2283 <refpurpose>Iterate over all the tuples of a
2284 query via a loop clause</refpurpose>
2285 <refclass>Loop Clause</refclass>
2288 <title>Compatibility</title>
2289 <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
2292 <title>Syntax</title>
2293 <synopsis><replaceable>var</replaceable> [<replaceable>type-spec</replaceable>] being {each | the} {record | records | tuple | tuples} {in | of} <replaceable>query</replaceable> [from <replaceable>database</replaceable>]</synopsis>
2296 <title>Arguments and Values</title>
2299 <term><parameter>var</parameter></term>
2301 <para>A <literal>d-var-spec</literal>, as defined in the
2302 grammar for <function>loop</function>-clauses in the
2303 ANSI Standard for Common Lisp. This allows for the
2304 usual loop-style destructuring.</para>
2308 <term><parameter>type-spec</parameter></term>
2310 <para>An optional <literal>type-spec</literal> either
2311 simple or destructured, as defined in the grammar for
2312 <function>loop</function>-clauses in the ANSI Standard
2313 for Common Lisp.</para>
2317 <term><parameter>query</parameter></term>
2319 <para>An <glossterm linkend="gloss-sql-expression">sql
2320 expression</glossterm> that represents an SQL
2321 query which is expected to return a (possibly empty)
2322 result set, where each tuple has as many attributes as
2323 <parameter>function</parameter> takes arguments.</para>
2327 <term><parameter>database</parameter></term>
2330 <glossterm linkend="gloss-database-object">database
2331 object</glossterm>. This will default to the value
2332 of <symbol>*default-database*</symbol>.</para>
2338 <title>Description</title>
2339 <para>This clause is an iteration driver for
2340 <function>loop</function>, that binds the given variable
2341 (possibly destructured) to the consecutive tuples (which are
2342 represented as lists of attribute values) in the result set
2343 returned by executing the SQL <parameter>query</parameter>
2344 expression on the <parameter>database</parameter>
2348 <title>Examples</title>
2350 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
2353 (loop with time-graph = (make-hash-table :test #'equal)
2354 with event-graph = (make-hash-table :test #'equal)
2355 for (time event) being the tuples of "select time,event from log"
2358 (incf (gethash time time-graph 0))
2359 (incf (gethash event event-graph 0))
2361 (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
2362 (format t "~&Time-Graph:~%===========~%")
2363 (maphash #'show-graph time-graph)
2364 (format t "~&~%Event-Graph:~%============~%")
2365 (maphash #'show-graph event-graph))
2366 (return (values time-graph event-graph)))
2375 >> CLOS Benchmark entry. => 9000
2376 >> Demo Text... => 3
2377 >> doit-text => 3000
2378 >> C Benchmark entry. => 12000
2379 >> CLOS Benchmark entry => 32000
2380 => #<EQUAL hash table, 3 entries {48350A1D}>
2381 => #<EQUAL hash table, 5 entries {48350FCD}>
2385 <title>Side Effects</title>
2386 <para>Whatever effects the execution of the SQL query has
2387 on the underlying database, if any.</para>
2390 <title>Affected by</title>
2394 <title>Exceptional Situations</title>
2395 <para>If the execution of the SQL query leads to any
2396 errors, an error of type
2397 <errortype>sql-database-error</errortype> is signalled.</para>
2398 <para>Otherwise, any of the exceptional situations of
2399 <function>loop</function> applies.</para>
2402 <title>See Also</title>
2405 <member><link linkend="query"><function>query</function></link></member>
2406 <member><link linkend="map-query"><function>map-query</function></link></member>
2407 <member><link linkend="do-query"><function>do-query</function></link></member>
2412 <title>Notes</title>