Introduction
Purpose
&clsql; is a Common Lisp interface to SQL databases. A number of Common
Lisp implementations and SQL databases are supported.The general
structure of &clsql; is based on the
CommonSQL package by Xanalys.
History
&clsql; is written by Kevin M. Rosenberg and based substantially
on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
are:
port from the &cmucl; FFI to &uffi;.
new &acl; ODBC interface back-end.
compatibility layer for &cmucl; specific code.
much improved robustness for the &mysql; back-end.
improved system loading.
improved packages and symbol export.
Prerequisites
&defsystem;
&clsql; uses &defsystem to compile and load its
components. &defsystem; is included in the &clocc; collection. The
version in the pre-packaged distribution is rather old and
may not function well. The version in CVS tree tree works quite
well. For convenience, a copy of the latest &defsystem; at the FTP
site
of &clsql;.
&uffi;
&clsql; uses &uffi;
as a Foreign Function Interface (FFI) to support multiple &cl;
implementations.
You can download &uffi; from its FTP site. There
are zip files for Microsoft Windows systems and gzipped tar files for
other systems.
XPTest (optional)
The test suite for &clsql; uses the onShore Development's
XPTest package. onShore has graciously put the package in the public
domain. You can download the package from onShore's web site.
This package is not required except if you wish to run the &clsql;
test suite.
Supported Common Lisp Implementation
The implementations that support &clsql; is governed by the supported
implementations of &uffi;. At the time of the initial release of &clsql;,
the following implementations are supported:
&acl; v6.1 on Redhat Linux 7.2 and Microsoft Windows.
&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.
&cmucl; 18d on Redhat Linux 7.2.
Supported &sql; Implementation
Currently, &clsql; supports the following databases:
&mysql; v3.23.49 on Redhat Linux 7.2 and Microsoft Windows.
&postgresql; v7.1 on Redhat Linux 7.2. Support for both direct API connections and TCP socket connections.
Allegro's ODBC interface (&aodbc;) on Redhat Linux 7.2 and Microsoft Windows.
Installation
Ensure &defsystem; is loaded
Simply load the file defsystem.lisp.
(load "defsystem.lisp")
Build &c; helper libraries
&clsql; uses functions that require 64-bit integer
parameters and return values. The &ffi; in most &clsql;
implementations do not support 64-bit integers. Thus, C helper
libraries are required to break these 64-bit integers into two compatible
32-bit integers.
Makefiles for Microsoft Windows and GNU/Solaris systems
are supplied to build the libraries. Since many Microsoft Windows
users don't have access to a compiler, the DLL and LIB
files for Microsoft Windows are supplied with the distribution.
To build the libraries on a GNU or Solaris, use the shell and
change to the root directory of &clsql;. You may need to edit the file
interfaces/mysql/Makefile to specify the location of your
MySQL installation. Then, you can give the command
make libs
in the root directory of &clsql; to build the libraries
interfaces/mysql/clsql-mysql.so and
interfaces/clsql-uffi/clsql-uffi.so.
Load &uffi;
Unzip or untar the &uffi; distribution which creates a directory
for the &uffi; files. Add that directory to Defsystem's mk:*central-registry*.
You can do that by either pushing the pathname of the directory onto this variable, or
use the new add-registry-location present in the newest versions of
&defsystem;. The following example code assumes the &uffi; files reside in the
/usr/local/src/lisp/uffi directory.
(mk:add-registry-location #P"/usr/local/src/lisp/uffi")
(mk:load-system :uffi)
Load &clsql; modules
Unzip or untar the &clsql; distribution which creates a directory
for the &clsql; files. Add that directory to Defsystem's mk:*central-registry*.
You can do that by either pushing the pathname of the directory onto this variable, or
use the new add-registry-location present in the newest versions of
&defsystem;. The following example code assumes the &clsql; files reside in the
/usr/local/src/lisp/clsql directory. You need to load, at a minimum,
the main :clsql system and at least one interface system.
(mk:add-registry-location #P"/usr/local/src/lisp/clsql")
(mk:load-system :clsql) ; main clsql package
(mk:load-system :clsql-mysql) ; MySQL interface
(mk:load-system :clsql-postgresql) ; PostgreSQL interface
(mk:load-system :clsql-postgresql-socket) ; Socket PGSQL interface
(mk:load-system :clsql-aodbc) ; Allegro ODBC interface