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 <!-- Object Oriented Data Definition Language -->
9 <reference id="ref-ooddl">
10 <title>Object Oriented Data Definition Language (OODDL)</title>
13 The Object Oriented Data Definition Language (OODDL) provides
14 access to relational SQL tables using Common Lisp Object System
15 (CLOS) objects. SQL tables are mapped to CLOS objects with the
16 SQL columns being mapped to slots of the CLOS object.
19 The mapping between SQL tables and CLOS objects is defined with
21 linkend="def-view-class"><function>def-view-class</function></link>. SQL
22 tables are created with <link
23 linkend="create-view-from-class"><function>create-view-from-class</function></link>
24 and SQL tables can be deleted with <link
25 linkend="drop-view-from-class"><function>drop-view-from-class</function></link>.
28 <para>The above functions refer to the Lisp
29 <emphasis>view</emphasis> of the SQL table. This Lisp view
30 should not be confused with SQL <function>VIEW</function>
35 <refentry id="standard-db-object">
37 <refname>STANDARD-DB-OBJECT</refname>
38 <refpurpose>Superclass for all &clsql; View Classes.</refpurpose>
39 <refclass>Class</refclass>
42 <title>Class Precedence List</title>
44 <simplelist type="inline">
45 <member><type>standard-db-object</type></member>
46 <member><type>standard-object</type></member>
47 <member><type>t</type></member>
52 <title>Description</title> <para>This class is the superclass
53 of all &clsql; View Classes.</para>
56 <title>Class details</title>
57 <programlisting>(defclass STANDARD-DB-OBJECT ()(...))</programlisting>
63 <member>slot VIEW-DATABASE is of type (OR NULL DATABASE)
64 which stores the associated database for the
71 <refentry id="default-string-length">
73 <refname>*DEFAULT-STRING-LENGTH*</refname>
74 <refpurpose>Default length of SQL strings.</refpurpose>
75 <refclass>Variable</refclass>
78 <title>Value Type</title>
84 <title>Initial Value</title>
85 <para><parameter>255</parameter></para>
88 <title>Description</title>
90 If a slot of a class defined by
91 <function>def-view-class</function> is of the type
92 <parameter>string</parameter> or
93 <parameter>varchar</parameter> and does not have a length
94 specified, then the value of this variable is used as SQL
99 <title>Examples</title>
101 (let ((*default-string-length* 80))
102 (def-view-class s80 ()
104 (b :type (string 80))
106 => #<Standard-Db-Class S80 {480A431D}>
108 (create-view-from-class 's80)
110 (table-exists-p [s80])
114 The above code causes a SQL table to be created with the SQL command
116 <screen>CREATE TABLE (A VARCHAR(80), B CHAR(80), C VARCHAR(80))</screen>
119 <title>Affected By</title>
121 Some SQL backends do not support
122 <parameter>varchar</parameter> lengths greater than 255.
126 <title>See Also</title>
131 <para>This is a CLSQL extension to the CommonSQL API.</para>
135 <refentry id="create-view-from-class">
137 <refname>CREATE-VIEW-FROM-CLASS</refname>
138 <refpurpose>Create a SQL table from a <glossterm linkend="gloss-view-class">View Class</glossterm>.</refpurpose>
139 <refclass>Function</refclass>
142 <title>Syntax</title>
144 <function>create-view-from-class</function> <replaceable>view-class-name</replaceable> &key <replaceable>database</replaceable> <replaceable>transactions</replaceable> => <returnvalue><!-- no values --></returnvalue></synopsis>
147 <title>Arguments and Values</title>
150 <term><parameter>view-class-name</parameter></term>
153 The name of a <glossterm linkend="gloss-view-class">View
154 Class</glossterm> that has been defined with <link
155 linkend="def-view-class"><function>def-view-class</function></link>.
160 <term><parameter>database</parameter></term>
164 linkend="gloss-database-object">database</glossterm> in
165 which to create the SQL table. This will default to the
166 value of <symbol>*default-database*</symbol>.
171 <term><parameter>transactions</parameter></term>
174 When &nil; specifies that a table type which does not
175 support transactions should be used.
182 <title>Description</title>
184 Creates a table as defined by the <glossterm
185 linkend="gloss-view-class">View Class</glossterm>
186 <parameter>view-class-name</parameter> in
187 <parameter>database</parameter>.
191 <title>Examples</title>
193 (def-view-class foo () ((a :type (string 80))))
194 => #<Standard-Db-Class FOO {4807F7CD}>
195 (create-view-from-class 'foo)
202 <title>Side Effects</title>
204 Causes a table to be created in the SQL database.
208 <title>Affected by</title>
210 Most SQL database systems will signal an error if a table
211 creation is attempted when a table with the same name already
212 exists. The SQL user, as specified in the database connection,
213 must have sufficient permission for table creation.
217 <title>Exceptional Situations</title>
219 A condition will be signaled if the table can not be created
224 <title>See Also</title>
227 <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
228 <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
235 Currently, only &mysql; supports transactionless
236 tables. &clsql; provides the ability to create such tables for
237 applications which would benefit from faster table access and
238 do not require transaction support.
241 The case of the table name is determined by the type of the
242 database. &mysql;, for example, creates databases in upper-case
243 while &postgresql; uses lowercase.
248 <refentry id="def-view-class">
250 <refname>DEF-VIEW-CLASS</refname>
251 <refpurpose>Defines CLOS classes with mapping to SQL database.</refpurpose>
252 <refclass>Macro</refclass>
255 <title>Syntax</title>
257 <function>def-view-class</function> <replaceable>name</replaceable> <replaceable>superclasses</replaceable> <replaceable>slots</replaceable> &rest <replaceable>class-options</replaceable> => <returnvalue>class</returnvalue></synopsis>
260 <title>Arguments and Values</title>
263 <term><parameter>name</parameter></term>
271 <term><parameter>superclasses</parameter></term>
274 The superclasses for the defined class.
279 <term><parameter>slots</parameter></term>
282 The class slot definitions.
287 <term><parameter>class options</parameter></term>
295 <term><parameter>class</parameter></term>
305 <title>Slot Options</title>
309 <parameter>:db-kind</parameter> - specifies the kind of
310 database mapping which is performed for this slot and
311 defaults to <parameter>:base</parameter> which indicates
312 that the slot maps to an ordinary column of the database
313 table. A <parameter>:db-kind</parameter> value of
314 <parameter>:key</parameter> indicates that this slot is a
315 special kind of <parameter>:base</parameter> slot which
316 maps onto a column which is one of the unique keys for the
317 database table, the value <parameter>:join</parameter>
318 indicates this slot represents a join onto another
319 <glossterm linkend="gloss-view-class">View Class</glossterm>
320 which contains View Class objects, and the value
321 <parameter>:virtual</parameter> indicates a standard CLOS
322 slot which does not map onto columns of the database
328 <parameter>:db-info</parameter> - if a slot is specified
329 with <parameter>:db-kind</parameter>
330 <parameter>:join</parameter>, the slot option
331 <parameter>:db-info</parameter> contains a property list
332 which specifies the nature of the join. The valid members
338 <parameter>:join-class</parameter>
339 <emphasis>class-name</emphasis> - the name of the
345 <parameter>:home-key</parameter>
346 <emphasis>slot-name</emphasis> - the name of the slot
347 of this class for joining
352 <parameter>:foreign-key</parameter>
353 <emphasis>slot-name</emphasis> - the name of the slot
354 of the <parameter>:join-class</parameter> for joining
359 <parameter>:target-slot</parameter>
360 <emphasis>target-slot</emphasis> - this is an optional
361 parameter. If specified, then the join slot of the
362 defining class will contain instances of this target
363 slot rather than of the join class. This can be useful
364 when the <parameter>:join-class</parameter> is an
365 intermediate class in a
366 <emphasis>many-to-many</emphasis> relationship and the
367 application is actually interested in the
368 <parameter>:target-slot</parameter>.
373 <parameter>:retrieval</parameter>
374 <emphasis>time</emphasis> - The default value is
375 <parameter>:deferred</parameter>, which defers filling
376 this slot until the value is accessed. The other valid
377 value is <parameter>:immediate</parameter> which
378 performs the SQL query when the instance of the class
379 is created. In this case, the
380 <parameter>:set</parameter> is automatically set to
386 <parameter>:set</parameter> <emphasis>set</emphasis> -
387 This controls what is stored in the join slot. The
388 default value is &t;. When <emphasis>set</emphasis> is
389 &t; and <emphasis>target-slot</emphasis> is undefined,
390 the join slot will contain a list of instances of the
391 join class. Whereas, if
392 <emphasis>target-slot</emphasis> is defined, then the
393 join slot will contain a list of pairs of
394 <emphasis>(target-value join-instance)</emphasis>.
395 When <emphasis>set</emphasis> is &nil;, the join slot
396 will contain a single instances.
403 <parameter>:type</parameter> - for slots of
404 <parameter>:db-kind</parameter> <parameter>:base</parameter> or
405 <parameter>:key</parameter>, the <parameter>:type</parameter> slot
406 option has a special interpretation such that Lisp
407 types, such as string, integer and float are
408 automatically converted into appropriate SQL types for
409 the column onto which the slot maps. This behaviour may
410 be overridden using the <parameter>:db-type</parameter> slot
411 option. The valid values are:
414 <parameter>string</parameter> - a variable length
415 character field up to <link
416 linkend="default-string-length">*default-string-length*</link>
420 <parameter>(string n)</parameter> - a fixed length
421 character field <parameter>n</parameter> characters
425 <parameter>varchar</parameter> - a variable length
426 character field up to <link
427 linkend="default-string-length">*default-string-length*</link>
431 <parameter>(varchar n)</parameter> - a variable length
432 character field up to <parameter>n</parameter>
433 characters in length.
436 <parameter>char</parameter> - a single character field
438 <member><parameter>integer</parameter> - signed integer
439 at least 32-bits wide</member>
440 <member><parameter>(integer n)</parameter></member>
441 <member><parameter>float</parameter></member>
442 <member><parameter>(float n)</parameter></member>
443 <member><parameter>long-float</parameter></member>
444 <member><parameter>number</parameter></member>
445 <member><parameter>(number n)</parameter></member>
446 <member><parameter>(number n p)</parameter></member>
448 <parameter>tinyint</parameter> - An integer column 8-bits
449 wide. [not supported by all database backends]
452 <parameter>smallint</parameter> - An integer column 16-bits
453 wide. [not supported by all database backends]
456 <parameter>bigint</parameter> - An integer column
457 64-bits wide. [not supported by all database backends]
460 <parameter>universal-time</parameter> - an integer
461 field sufficiently wide to store a
462 universal-time. On most databases, a slot of this
463 type assigned a SQL type of
464 <parameter>BIGINT</parameter>
467 <parameter>wall-time</parameter> - a slot which stores
468 a date and time in a SQL timestamp column. &clsql;
469 provides a number of time manipulation functions to
470 support objects of type <type>wall-time</type>.
473 <parameter>duration</parameter> - stores a
474 <type>duration</type> structure. &clsql; provides
475 routines for <type>wall-time</type> and
476 <type>duration</type> processing.
478 <member><parameter>boolean</parameter> - stores a &t; or
479 &nil; value.</member>
481 <parameter>generalized-boolean</parameter> - similar
482 to a <parameter>boolean</parameter> in that either a
483 &t; or &nil; value is stored in the SQL
484 database. However, any Lisp object can be stored in
485 the Lisp object. A Lisp value of &nil; is stored as
486 <constant>FALSE</constant> in the database, any
487 other Lisp value is stored as
488 <constant>TRUE</constant>.
491 <parameter>keyword</parameter> - stores a keyword
493 <member><parameter>symbol</parameter> - stores a symbol</member>
495 <parameter>list</parameter> - stores a list by writing
496 it to a string. The items in the list must be able to
499 <member><parameter>vector</parameter> - stores a vector
500 similarly to <parameter>list</parameter></member>
501 <member><parameter>array</parameter> - stores a array
502 similarly to <parameter>list</parameter></member>
509 <parameter>:column</parameter> - specifies the name of
510 the SQL column which the slot maps onto, if
511 <parameter>:db-kind</parameter> is not
512 <parameter>:virtual</parameter>, and defaults to the
513 slot name. If the slot name is used for the SQL column
514 name, any hypens in the slot name are converted
515 to underscore characters.
520 <parameter>:void-value</parameter> - specifies the value
521 to store in the Lisp instance if the SQL value is NULL and
527 <parameter>:db-constraints</parameter> - is a keyword
528 symbol representing an SQL column constraint expression or
529 a list of such symbols. The following column constraints
530 are supported: <symbol>:not-null</symbol>,
531 <symbol>:primary-key</symbol>, <symbol>:unique</symbol>,
532 <symbol>:unsigned</symbol> (&mysql; specific),
533 <symbol>:zerofill</symbol> (&mysql; specific) and
534 <symbol>:auto-increment</symbol> (&mysql; specific).
539 <parameter>:db-type</parameter> - a string to specify the SQL
540 column type. If specified, this string overrides the SQL
541 column type as computed from the <parameter>:type</parameter>
548 <title>Class Options</title>
553 <parameter>:base-table</parameter> - specifies the name
554 of the SQL database table. The default value is the
555 class name. Like slot names, hypens in the class name
556 are converted to underscore characters.
563 <title>Description</title>
565 Creates a <glossterm linkend="gloss-view-class">View
566 Class</glossterm> called <parameter>name</parameter> whose
567 slots <parameter>slots</parameter> can map onto the attributes
568 of a table in a database. If
569 <parameter>superclasses</parameter> is &nil; then the
570 superclass of <parameter>class</parameter> will be
571 <parameter>standard-db-object</parameter>, otherwise
572 <parameter>superclasses</parameter> is a list of superclasses
573 for <parameter>class</parameter> which must include
574 <parameter>standard-db-object</parameter> or a descendent of
580 <title>Examples</title>
582 The following examples are from the &clsql; test suite.
585 (def-view-class person (thing)
586 ((height :db-kind :base :accessor height :type float
588 (married :db-kind :base :accessor married :type boolean
590 (birthday :type clsql:wall-time :initarg :birthday)
591 (bd-utime :type clsql:universal-time :initarg :bd-utime)
592 (hobby :db-kind :virtual :initarg :hobby :initform nil)))
594 (def-view-class employee (person)
597 :db-constraints :not-null
602 :db-constraints :not-null
608 :initarg :first-name)
614 :accessor employee-email
621 :accessor employee-company
623 :db-info (:join-class company
625 :foreign-key companyid
631 :accessor employee-manager
633 :db-info (:join-class employee
638 :accessor employee-addresses
640 :db-info (:join-class employee-address
645 (:base-table employee))
647 (def-view-class company ()
650 :db-constraints :not-null
655 :db-constraints :not-null
663 :initarg :presidentid)
667 :db-info (:join-class employee
668 :home-key presidentid
672 :reader company-employees
674 :db-info (:join-class employee
675 :home-key (companyid groupid)
676 :foreign-key (ecompanyid groupid)
679 (def-view-class address ()
682 :db-constraints :not-null
687 :initarg :street-number)
691 :initarg :street-name)
694 :void-value "no city"
701 :initarg :postal-code))
704 ;; many employees can reside at many addressess
705 (def-view-class employee-address ()
706 ((aemplid :type integer :initarg :emplid)
707 (aaddressid :type integer :initarg :addressid)
708 (verified :type boolean :initarg :verified)
709 (address :db-kind :join
710 :db-info (:join-class address
712 :foreign-key addressid
713 :retrieval :immediate)))
714 (:base-table "ea_join"))
716 (def-view-class deferred-employee-address ()
717 ((aemplid :type integer :initarg :emplid)
718 (aaddressid :type integer :initarg :addressid)
719 (verified :type boolean :initarg :verified)
720 (address :db-kind :join
721 :db-info (:join-class address
723 :foreign-key addressid
726 (:base-table "ea_join"))
730 <title>Side Effects</title>
731 <para>Creates a new CLOS class.</para>
734 <title>Affected by</title>
740 <title>Exceptional Situations</title>
746 <title>See Also</title>
749 <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
750 <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
751 <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
758 The actual SQL type for a column depends up the database type
759 in which the SQL table is stored. As an example, the view
760 class type <parameter>(varchar 100)</parameter> specifies a
761 SQL column type <parameter>VARCHAR(100)</parameter> in &mysql;
762 and a column type <parameter>VARCHAR2(100)</parameter> in
766 The actual lisp type for a slot may be different than the
767 value specified by the <parameter>:type</parameter> attribute.
768 For example, a slot declared with "<parameter>:type (string
769 30)</parameter>" actually sets the slots Lisp type as
770 <parameter>(or null string)</parameter>. This is to allow a
771 &nil; value or a string shorter than 30 characters to be
777 <refentry id="drop-view-from-class">
779 <refname>DROP-VIEW-FROM-CLASS</refname>
780 <refpurpose>Delete table from SQL database.</refpurpose>
781 <refclass>Function</refclass>
784 <title>Syntax</title>
786 <function>drop-view-from-class</function> <replaceable>view-class-name</replaceable> &key <replaceable>database</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
789 <title>Arguments and Values</title>
792 <term><parameter>view-class-name</parameter></term>
795 The name of the <glossterm linkend="gloss-view-class">View
801 <term><parameter>database</parameter></term>
804 <glossterm linkend="gloss-database-object">database
805 object</glossterm>. This will default to the value of
806 <symbol>*default-database*</symbol>.
813 <title>Description</title>
814 <para>Removes a table defined by the <glossterm
815 linkend="gloss-view-class">View Class</glossterm>
816 <parameter>view-class-name</parameter> from
817 <parameter>database</parameter> which defaults to
818 <parameter>*default-database*</parameter>.
822 <title>Examples</title>
826 (drop-view-from-class 'foo)
833 <title>Side Effects</title>
835 Deletes a table from the SQL database.
839 <title>Affected by</title>
841 Whether the specified table exists in the SQL database.
845 <title>Exceptional Situations</title>
847 A condition may be signalled if the table does not exist in
848 the SQL database or if the SQL connection does not have
849 sufficient permissions to delete tables.
853 <title>See Also</title>
856 <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
857 <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
869 <refentry id="list-classes">
871 <refname>LIST-CLASSES</refname>
872 <refpurpose>List classes for tables in SQL database.</refpurpose>
873 <refclass>Function</refclass>
876 <title>Syntax</title>
878 <function>list-classes</function> &key <replaceable>test</replaceable> <replaceable>root-class</replaceable> <replaceable>database</replaceable> => <returnvalue>classes</returnvalue></synopsis>
881 <title>Arguments and Values</title>
884 <term><parameter>test</parameter></term>
887 a function used to filter the search. By default, <parameter>identity</parameter> is used which
888 will return all classes.
893 <term><parameter>root-class</parameter></term>
896 specifies the root class to the search. By default,
897 <parameter>standard-db-object</parameter> is used which
898 is the root for all view classes.
903 <term><parameter>database</parameter></term>
907 linkend="gloss-database-object">database</glossterm> to
908 search for view classes. This will default to the value
909 of <symbol>*default-database*</symbol>.
914 <term><parameter>classes</parameter></term>
917 List of view classes.
924 <title>Description</title>
925 <para>Returns a list of all the View Classes which have been
926 defined in the Lisp session and are connected to
927 <parameter>database</parameter> and which descended from the
928 class <parameter>root-class</parameter> and which satisfy the
929 function <parameter>test</parameter>.
933 <title>Examples</title>
936 => (#<clsql-sys::standard-db-class big> #<clsql-sys::standard-db-class employee-address>
937 #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company>
938 #<clsql-sys::standard-db-class employee>)
940 (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
941 => (#<clsql-sys::standard-db-class employee-address> #<clsql-sys::standard-db-class address>
942 #<clsql-sys::standard-db-class company> #<clsql-sys::standard-db-class employee>)
946 <title>Side Effects</title>
952 <title>Affected by</title>
955 <member>Which view classes have been defined in the Lisp
961 <title>Exceptional Situations</title>
967 <title>See Also</title>
970 <member><link linkend="def-view-class"><function>def-view-class</function></link></member>