<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
+<!ENTITY % myents SYSTEM "entities.inc">
%myents;
]>
<reference id="clsql">
<title><symbol>CLSQL</symbol></title>
<partintro>
- <para>This part gives a reference to all the symbols exported
- from the package <symbol>CLSQL-SYS</symbol>, which are also
- re-exported from the package <symbol>CLSQL</symbol>. These
- symbols constitute the normal user-interface of
- &clsql;.</para>
+ <para>This part gives a reference to the symbols exported from the
+ package <symbol>CLSQL-SYS</symbol>, which are also re-exported
+ from the package <symbol>CLSQL</symbol>. These symbols constitute
+ the normal user-interface of &clsql;. Currently, the symbols of
+ the &commonsql;-API are not documented here.</para>
</partintro>
<!-- Conditions -->
<refentry id="clsql-condition">
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(setf *default-database-type* :mysql)
=> :mysql
(initialize-database-type)
=> t
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Affected By</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(setf *default-database-type* :mysql)
=> :mysql
(initialize-database-type)
=> t
*initialized-database-types*
=> (:MYSQL)
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Affected By</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
*initialized-database-types*
=> NIL
(setf *default-database-type* :mysql)
=> T
*initialized-database-types*
=> (:MYSQL)
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(connected-databases)
=> NIL
(connect '(nil "template1" "dent" nil) :database-type :postgresql)
=> T
(connected-databases)
=> NIL
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(connected-databases)
=> NIL
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
=> NIL
(connected-databases)
=> NIL
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Affected By</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
=> "www.pmsf.de/template1/dent"
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
=> NIL
(find-database **)
=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
>> (SETQ RESULT OLD-DB)))
>> 0] 0
=> #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(disconnect :database (find-database "dent/newesim/dent"))
=> T
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(disconnect-pool)
=> T
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
</refentry>
+ <refentry id="create_db">
+ <refnamediv>
+ <refname>CREATE-DATABASE</refname>
+ <refpurpose>create a database</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection-spec</parameter></term>
+ <listitem>
+ <para>A connection specification</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database-type</parameter></term>
+ <listitem>
+ <para>A database type specifier, i.e. a keyword.
+ This defaults to the value of
+ <symbol>*default-database-type*</symbol></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>success</parameter></term>
+ <listitem>
+ <para>A boolean flag. If &t;, a new database was
+ successfully created.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>This function creates a database in the database system
+ specified by <parameter>database-type</parameter>.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
+=> T
+
+(create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
+=>
+Error: While trying to access database localhost/new/dent
+ using database-type MYSQL:
+ Error database-create failed: mysqladmin: connect to server at 'localhost' failed
+error: 'Access denied for user: 'root@localhost' (Using password: YES)'
+ has occurred.
+ [condition type: CLSQL-ACCESS-ERROR]
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>A database will be created on the filesystem of the host.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>An exception will be thrown if the database system does
+ not allow new databases to be created or if database creation
+ fails.</para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>This function may invoke the operating systems
+ functions. Thus, some database systems may require the
+ administration functions to be available in the current
+ <symbol>PATH</symbol>. At this time, the
+ <symbol>:mysql</symbol> backend requires
+ <filename>mysqladmin</filename> and the
+ <symbol>:postgresql</symbol> backend requires
+ <filename>createdb</filename>.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="destroy_db">
+ <refnamediv>
+ <refname>DESTROY-DATABASE</refname>
+ <refpurpose>destroys a database</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection-spec</parameter></term>
+ <listitem>
+ <para>A connection specification</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database-type</parameter></term>
+ <listitem>
+ <para>A database type specifier, i.e. a keyword.
+ This defaults to the value of
+ <symbol>*default-database-type*</symbol></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>success</parameter></term>
+ <listitem>
+ <para>A boolean flag. If &t;, the database was
+ successfully destroyed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>This function destroy a database in the database system
+ specified by <parameter>database-type</parameter>.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=> T
+
+(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=>
+Error: While trying to access database localhost/test2/root
+ using database-type POSTGRESQL:
+ Error database-destory failed: dropdb: database removal failed: ERROR: database "test2" does not exist
+ has occurred.
+ [condition type: CLSQL-ACCESS-ERROR]
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>A database will be removed from the filesystem of the host.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>An exception will be thrown if the database system does not
+ allow databases to be removed, the database does not exist, or
+ if database removal fails.</para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>This function may invoke the operating systems
+ functions. Thus, some database systems may require the
+ administration functions to be available in the current
+ <symbol>PATH</symbol>. At this time, the
+ <symbol>:mysql</symbol> backend requires
+ <filename>mysqladmin</filename> and the
+ <symbol>:postgresql</symbol> backend requires
+ <filename>dropdb</filename>.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="probe_db">
+ <refnamediv>
+ <refname>PROBE-DATABASE</refname>
+ <refpurpose>tests for existence of a database</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection-spec</parameter></term>
+ <listitem>
+ <para>A connection specification</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>database-type</parameter></term>
+ <listitem>
+ <para>A database type specifier, i.e. a keyword.
+ This defaults to the value of
+ <symbol>*default-database-type*</symbol></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>success</parameter></term>
+ <listitem>
+ <para>A boolean flag. If &t;, the database exists
+ in the database system.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>This function tests for the existence of a database in
+ the database system specified by
+ <parameter>database-type</parameter>.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=> T
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>None</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>An exception maybe thrown if the database system does
+ not receive administrator-level authentication since function
+ may need to read the administrative database of the database
+ system.</para>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
+
<refentry id="database-name-from-spec">
<refnamediv>
<refname>DATABASE-NAME-FROM-SPEC</refname>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
=> NIL
(find-database **)
=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(execute-command "create table eventlog (time char(30),event char(70))")
=> T
(execute-command "drop table eventlog")
=> T
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refnamediv>
<refsect1>
<title>Syntax</title>
- <synopsis><function>query</function> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
+ <synopsis><function>query</function> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>result-types</replaceable> => <returnvalue>result</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>types</parameter></term>
+ <term><parameter>result-types</parameter></term>
<listitem>
<para>A
<glossterm linkend="gloss-field-types">field type
- specififier</glossterm>. The default is &nil;.
+ specifier</glossterm>. The default is &nil;.
</para>
<para>
The purpose of this argument is cause &clsql; to
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(execute-command "create table simple (name char(50), salary numeric(10,2))")
=> T
(execute-command "insert into simple values ('Mai, Pierre',10000)")
;; MySQL-specific:
(query "show tables")
=> (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refnamediv>
<refsect1>
<title>Syntax</title>
- <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
+ <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>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>types</parameter></term>
+ <term><parameter>result-types</parameter></term>
<listitem>
<para>
- A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
+ A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
The default is &nil;. See <link
linkend="query"><function>query</function></link>
for the semantics of this argument.
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(map-query 'list #'(lambda (salary name)
(declare (ignorable name))
(read-from-string salary))
list))
=> NIL
=> (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refnamediv>
<refsect1>
<title>Syntax</title>
- <synopsis><function>do-query</function> ((&rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable>) &body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
+ <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>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>types</parameter></term>
+ <term><parameter>result-types</parameter></term>
<listitem>
<para>
- A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
+ A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
The default is &nil;. See <link
linkend="query"><function>query</function></link>
for the semantics of this argument.
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(do-query ((salary name) "select salary,name from simple")
(format t "~30A gets $~2,5$~%" name (read-from-string salary)))
>> Mai, Pierre gets $10000.00
(do-query ((salary name) "select salary,name from simple")
(return (cons salary name)))
=> ("10000.00" . "Mai, Pierre")
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
</refsect1>
<refsect1>
<title>Examples</title>
- <programlisting>
+ <screen>
(defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
"My database"
=> *MY-DB*
>> CLOS Benchmark entry => 32000
=> #<EQUAL hash table, 3 entries {48350A1D}>
=> #<EQUAL hash table, 5 entries {48350FCD}>
- </programlisting>
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
projects / clsql.git / blobdiff