RDBMS based CLOS persistency (iow ORM for CLOS)


The class metaobject called persistent-class in cl-perec extends the CLOS standard-class and allows classes to have persistent slots. In fact defpclass is nothing more than a defclass with a (:metaclass persistent-class). In a persistent class all slots are persistent by default unless the :persistent nil slot option is specified in which case the slot will be a standard slot. The persistent-class implements a subset of the CL type system and maps slots to RDBMS tables and columns. For several primitive types this can be done efficiently while some CL types need to be serialized and stored as BLOB in the RDBMS.

The intention of cl-perec is to completely hide the RDBMS part from the user. It creates and alters tables automatically (signals continuable errors for schema changes) so the user can mostly think in CLOS terms.

There is another class metaobject called persistent-association which allows two slots in two different classes to be in referential integrity. There are three different kind of associations: one-to-one, one-to-many and many-to-many. The many association end means an unordered set of persistent objects.

Another nice part is the query compiler which provides a convenient way to express queries in the lisp type system which is then mapped to efficient SQL queries if possible. Even if the entire query cannot be mapped to a single SQL statement, parts of it will transparently be run in the Lisp VM. Ordering, slot accessors, literals and lisp predicates can be used to build the query, see the huge number of tests for more details.

The persistent type system supports a subset of the Common Lisp type system, type aliasing and subtyping are transparently mapped to RDBMS. New primitive persistent types can be defined with defptype and defmapping. The extended metaobject protocol allows mapping lisp types to multiple RDBMS columns (e.g. the type (or null unbound integer) needs two columns).

Try it

If you want to try cl-perec but don't want to waste time installing all the necessary libraries only to try it, then grab the prebuilt 32 bit linux binary distribution uploaded at 2008-02-24! Unpack and start the executable (an SBCL core) and it will print a short description on how to set up PostgreSQL, connect using SLIME and some simple examples to paste. If PostgreSQL is up and running, and you have SLIME already configured then this should take less then a few minutes...


You can take a look at a very simple showcase or a somewhat less abstract and easier to understand web shop. But we suggest to check out the tests in the darcs repo for more details. You can run a huge number of test cases with (asdf:operate 'asdf:test-op :cl-perec-test.postgresql) and most of them should usually pass. You can also check out the code coverage report generated by Juho Snellman's experimental tool.


The current version is heavily tested under SBCL 1.0+ on Linux x86_64 using PostgreSQL 8.3. In principle it should be pretty easy to support other RDBMS systems because the mapping uses standard SQL features, although it requires reflection support (which is missing from e.g. Sqlite).

The RDBMS access is implemented using cl-rdbms. Look there for an updated list of the supported backends. As for MOP compatibility: it was only tested on SBCL, but it was designed to be portable, so we are only expecting minor issues when porting.


There's not much at the moment other than the source code and the test suite. Here is a generated documentation.

Mailing Lists

Project members

Levente Mészáros
Tamás Borbély
Attila Lendvai


You can browse the cl-perec darcs repository or get the tree with

darcs get

Important note: cl-perec might require non official versions of some libraries included under the cl-dwim project. To get these, see the darcs repositories of cl-dwim (for example: darcs get At the time of writing the metacopy and postmodern libs need to be pulled from cl-dwim, but this always changes, because we are periodically sending our changes to the maintainers of the official repos. In case of any problem please drop a mail to the list.


BSD / Public Domain