# 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 LispWorks Ltd.

## History

The &clsql; project was started by Kevin M. Rosenberg in 2001 to support SQL access on multiple Common Lisp implementations using the &uffi; library. The initial code was based substantially on Pierre R. Mai's excellent &maisql; package. In late 2003, the &usql; library was orphaned by its author, onShore Development, Inc. In April 2004, Marcus Pearce ported the &usql; library to &clsql;. The &usql; library provides a &commonsql;-compatible API for &clsql;.

The main changes from &maisql; and &usql; are:

- Port from the &cmucl; FFI to &uffi; which provide compatibility with the major Common Lisp implementations.

- Optimized loading of integer and floating-point fields.

- Additional database backends: &odbc;, &aodbc;, &sqlite; and &sqlite3;.

- A compatibility layer for &cmucl; specific code.

- Much improved robustness for the &mysql; back-end along with version 4 client library support.

- Improved library loading and installation documentation.

- Improved packages and symbol export.

- Pooled connections.

- Integrated transaction support for the classic &maisql; iteration macros.

## Prerequisites

### &asdf;

&clsql; uses &asdf; to compile and load its components. &asdf; is included in the &cclan; collection.

### &uffi;

&clsql; uses &uffi; as a Foreign Function Interface (FFI) to support multiple &cl; implementations.

### &md5;

&clsql;'s postgresql-socket interface uses Pierre Mai's md5 module.

### Supported Common Lisp Implementation

The implementations that support &clsql; is governed by the supported implementations of &uffi;. The following implementations are supported:

- &acl; v6.2 through 8.0 on Debian Linux x86 & x86_64 & PowerPC, FreeBSD 4.5, and Microsoft Windows XP.

- &lw; v4.3 and v4.4 on Debian Linux and Microsoft Windows XP.

- &cmucl; 18e on Debian Linux, FreeBSD 4.5, and Solaris 2.8. 19c on Debian Linux.

- &sbcl; 0.8.4 through 0.9.16 on Debian Linux.

- &scl; 1.1.1 on Debian Linux.

- &openmcl; 0.14 PowerPC and 1.0pre AMD64 on Debian Linux .

### Supported &sql; Implementation

&clsql; supports the following databases:

- &mysql; (tested v3.23.51, v4.0.18, 5.0.24).

- &postgresql; (tested with v7.4 and 8.0 with both direct API and TCP socket connections.

- &sqlite;.

- &sqlite3;.

- Direct &odbc; interface.

- &oracle; OCI.

- Allegro's DB interface (&aodbc;).

## Installation

### Ensure &asdf; is loaded

Simply load the file `asdf.lisp`.

    (load "asdf.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. The helper libraries reside in the directories `uffi` and `db-mysql`.

#### &mswindows;

Files named `Makefile.msvc` are supplied for building the libraries under Microsoft Windows. Since &mswindows; does not come with that compiler, compiled `DLL` and `LIB` library files are supplied with &clsql;.

#### &unix;

Files named `Makefile` are supplied for building the libraries under &unix;. Loading the `.asd` files automatically invokes make when necessary. So, manual building of the helper libraries is not necessary on most &unix; systems. However, the location of the &mysql; library files and include files may need to adjusted in `db-mysql/Makefile` on non-Debian systems.

### Add &uffi; path

Unzip or untar the &uffi; distribution which creates a directory for the &uffi; files. Add that directory to &asdf;'s `asdf:*central-registry*`. You can do that by pushing the pathname of the directory onto this variable. The following example code assumes the &uffi; files reside in the `/usr/share/lisp/uffi/` directory.

    (push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)

### Add &md5; path

If you plan to use the clsql-postgresql-socket interface, you must load the md5 module. Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files. Add that directory to &asdf;'s `asdf:*central-registry*`. You can do that by pushing the pathname of the directory onto this variable. The following example code assumes the cl-md5 files reside in the `/usr/share/lisp/cl-md5/` directory.

    (push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)

### Add &clsql; path and load module

Unzip or untar the &clsql; distribution which creates a directory for the &clsql; files. Add that directory to &asdf;'s `asdf:*central-registry*`. You can do that by pushing the pathname of the directory onto this variable. The following example code assumes the &clsql; files reside in the `/usr/share/lisp/clsql/` directory. You need to load the clsql system.

    (push #P"/usr/share/lisp/clsql/" asdf:*central-registry*)
    (asdf:operate 'asdf:load-op 'clsql)                   ; main CLSQL package

### Run test suite (optional)

The test suite can be executed using the &asdf; test-op operator. If &clsql; has not been loaded with asdf:load-op, the asdf:test-op operator will automatically load &clsql;. A configuration file named `.clsql-test.config` must be created in your home directory. There are instructures on the format of that file in the `tests/README`. After creating `.clsql-test.config`, you can run the test suite with &asdf;:

    	  (asdf:operate 'asdf:test-op 'clsql)