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>date</parameter> - a slot which stores the
474 date (without any time of day resolution) in a
475 column. &clsql; provides a number of time
476 manipulation functions that operate on date values.
479 <parameter>duration</parameter> - stores a
480 <type>duration</type> structure. &clsql; provides
481 routines for <type>wall-time</type> and
482 <type>duration</type> processing.
484 <member><parameter>boolean</parameter> - stores a &t; or
485 &nil; value.</member>
487 <parameter>generalized-boolean</parameter> - similar
488 to a <parameter>boolean</parameter> in that either a
489 &t; or &nil; value is stored in the SQL
490 database. However, any Lisp object can be stored in
491 the Lisp object. A Lisp value of &nil; is stored as
492 <constant>FALSE</constant> in the database, any
493 other Lisp value is stored as
494 <constant>TRUE</constant>.
497 <parameter>keyword</parameter> - stores a keyword
499 <member><parameter>symbol</parameter> - stores a symbol</member>
501 <parameter>list</parameter> - stores a list by writing
502 it to a string. The items in the list must be able to
505 <member><parameter>vector</parameter> - stores a vector
506 similarly to <parameter>list</parameter></member>
507 <member><parameter>array</parameter> - stores a array
508 similarly to <parameter>list</parameter></member>
515 <parameter>:column</parameter> - specifies the name of
516 the SQL column which the slot maps onto, if
517 <parameter>:db-kind</parameter> is not
518 <parameter>:virtual</parameter>, and defaults to the
519 slot name. If the slot name is used for the SQL column
520 name, any hypens in the slot name are converted
521 to underscore characters.
526 <parameter>:void-value</parameter> - specifies the value
527 to store in the Lisp instance if the SQL value is NULL and
533 <parameter>:db-constraints</parameter> - is a keyword
534 symbol representing an SQL column constraint expression or
535 a list of such symbols. The following column constraints
536 are supported: <symbol>:not-null</symbol>,
537 <symbol>:primary-key</symbol>, <symbol>:unique</symbol>,
538 <symbol>:unsigned</symbol> (&mysql; specific),
539 <symbol>:zerofill</symbol> (&mysql; specific) and
540 <symbol>:auto-increment</symbol> (&mysql; specific).
545 <parameter>:db-type</parameter> - a string to specify the SQL
546 column type. If specified, this string overrides the SQL
547 column type as computed from the <parameter>:type</parameter>
554 <title>Class Options</title>
559 <parameter>:base-table</parameter> - specifies the name
560 of the SQL database table. The default value is the
561 class name. Like slot names, hypens in the class name
562 are converted to underscore characters.
569 <title>Description</title>
571 Creates a <glossterm linkend="gloss-view-class">View
572 Class</glossterm> called <parameter>name</parameter> whose
573 slots <parameter>slots</parameter> can map onto the attributes
574 of a table in a database. If
575 <parameter>superclasses</parameter> is &nil; then the
576 superclass of <parameter>class</parameter> will be
577 <parameter>standard-db-object</parameter>, otherwise
578 <parameter>superclasses</parameter> is a list of superclasses
579 for <parameter>class</parameter> which must include
580 <parameter>standard-db-object</parameter> or a descendent of
586 <title>Examples</title>
588 The following examples are from the &clsql; test suite.
591 (def-view-class person (thing)
592 ((height :db-kind :base :accessor height :type float
594 (married :db-kind :base :accessor married :type boolean
596 (birthday :type clsql:wall-time :initarg :birthday)
597 (bd-utime :type clsql:universal-time :initarg :bd-utime)
598 (hobby :db-kind :virtual :initarg :hobby :initform nil)))
600 (def-view-class employee (person)
603 :db-constraints :not-null
608 :db-constraints :not-null
614 :initarg :first-name)
620 :accessor employee-email
627 :accessor employee-company
629 :db-info (:join-class company
631 :foreign-key companyid
637 :accessor employee-manager
639 :db-info (:join-class employee
644 :accessor employee-addresses
646 :db-info (:join-class employee-address
651 (:base-table employee))
653 (def-view-class company ()
656 :db-constraints :not-null
661 :db-constraints :not-null
669 :initarg :presidentid)
673 :db-info (:join-class employee
674 :home-key presidentid
678 :reader company-employees
680 :db-info (:join-class employee
681 :home-key (companyid groupid)
682 :foreign-key (ecompanyid groupid)
685 (def-view-class address ()
688 :db-constraints :not-null
693 :initarg :street-number)
697 :initarg :street-name)
700 :void-value "no city"
707 :initarg :postal-code))
710 ;; many employees can reside at many addressess
711 (def-view-class employee-address ()
712 ((aemplid :type integer :initarg :emplid)
713 (aaddressid :type integer :initarg :addressid)
714 (verified :type boolean :initarg :verified)
715 (address :db-kind :join
716 :db-info (:join-class address
718 :foreign-key addressid
719 :retrieval :immediate)))
720 (:base-table "ea_join"))
722 (def-view-class deferred-employee-address ()
723 ((aemplid :type integer :initarg :emplid)
724 (aaddressid :type integer :initarg :addressid)
725 (verified :type boolean :initarg :verified)
726 (address :db-kind :join
727 :db-info (:join-class address
729 :foreign-key addressid
732 (:base-table "ea_join"))
736 <title>Side Effects</title>
737 <para>Creates a new CLOS class.</para>
740 <title>Affected by</title>
746 <title>Exceptional Situations</title>
752 <title>See Also</title>
755 <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
756 <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
757 <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
764 The actual SQL type for a column depends up the database type
765 in which the SQL table is stored. As an example, the view
766 class type <parameter>(varchar 100)</parameter> specifies a
767 SQL column type <parameter>VARCHAR(100)</parameter> in &mysql;
768 and a column type <parameter>VARCHAR2(100)</parameter> in
772 The actual lisp type for a slot may be different than the
773 value specified by the <parameter>:type</parameter> attribute.
774 For example, a slot declared with "<parameter>:type (string
775 30)</parameter>" actually sets the slots Lisp type as
776 <parameter>(or null string)</parameter>. This is to allow a
777 &nil; value or a string shorter than 30 characters to be
783 <refentry id="drop-view-from-class">
785 <refname>DROP-VIEW-FROM-CLASS</refname>
786 <refpurpose>Delete table from SQL database.</refpurpose>
787 <refclass>Function</refclass>
790 <title>Syntax</title>
792 <function>drop-view-from-class</function> <replaceable>view-class-name</replaceable> &key <replaceable>database</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
795 <title>Arguments and Values</title>
798 <term><parameter>view-class-name</parameter></term>
801 The name of the <glossterm linkend="gloss-view-class">View
807 <term><parameter>database</parameter></term>
810 <glossterm linkend="gloss-database-object">database
811 object</glossterm>. This will default to the value of
812 <symbol>*default-database*</symbol>.
819 <title>Description</title>
820 <para>Removes a table defined by the <glossterm
821 linkend="gloss-view-class">View Class</glossterm>
822 <parameter>view-class-name</parameter> from
823 <parameter>database</parameter> which defaults to
824 <parameter>*default-database*</parameter>.
828 <title>Examples</title>
832 (drop-view-from-class 'foo)
839 <title>Side Effects</title>
841 Deletes a table from the SQL database.
845 <title>Affected by</title>
847 Whether the specified table exists in the SQL database.
851 <title>Exceptional Situations</title>
853 A condition may be signalled if the table does not exist in
854 the SQL database or if the SQL connection does not have
855 sufficient permissions to delete tables.
859 <title>See Also</title>
862 <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
863 <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
875 <refentry id="list-classes">
877 <refname>LIST-CLASSES</refname>
878 <refpurpose>List classes for tables in SQL database.</refpurpose>
879 <refclass>Function</refclass>
882 <title>Syntax</title>
884 <function>list-classes</function> &key <replaceable>test</replaceable> <replaceable>root-class</replaceable> <replaceable>database</replaceable> => <returnvalue>classes</returnvalue></synopsis>
887 <title>Arguments and Values</title>
890 <term><parameter>test</parameter></term>
893 a function used to filter the search. By default, <parameter>identity</parameter> is used which
894 will return all classes.
899 <term><parameter>root-class</parameter></term>
902 specifies the root class to the search. By default,
903 <parameter>standard-db-object</parameter> is used which
904 is the root for all view classes.
909 <term><parameter>database</parameter></term>
913 linkend="gloss-database-object">database</glossterm> to
914 search for view classes. This will default to the value
915 of <symbol>*default-database*</symbol>.
920 <term><parameter>classes</parameter></term>
923 List of view classes.
930 <title>Description</title>
931 <para>Returns a list of all the View Classes which have been
932 defined in the Lisp session and are connected to
933 <parameter>database</parameter> and which descended from the
934 class <parameter>root-class</parameter> and which satisfy the
935 function <parameter>test</parameter>.
939 <title>Examples</title>
942 => (#<clsql-sys::standard-db-class big> #<clsql-sys::standard-db-class employee-address>
943 #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company>
944 #<clsql-sys::standard-db-class employee>)
946 (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
947 => (#<clsql-sys::standard-db-class employee-address> #<clsql-sys::standard-db-class address>
948 #<clsql-sys::standard-db-class company> #<clsql-sys::standard-db-class employee>)
952 <title>Side Effects</title>
958 <title>Affected by</title>
961 <member>Which view classes have been defined in the Lisp
967 <title>Exceptional Situations</title>
973 <title>See Also</title>
976 <member><link linkend="def-view-class"><function>def-view-class</function></link></member>