The CL-postgres module implements a rather low-level interface for communicating with a PostgreSQL database server. It is part of the Postmodern library, but can be used separately.
Objects of this type represent database connections.
function
open-database (database user password host &optional (port 5432))
→ database-connection
Create and open a connection for the specified server, database, and user.
function close-database (database-connection)
Close a database connection. It is advisable to call this on connections when you are done with them. Otherwise the open socket will stick around until it is garbage collected, and no one will tell the database server that we are done with it.
function reopen-database (database-connection)
Re-establish a database connection for a previously closed connection object. (Calling this on a connection that is still open is harmless.)
function
database-open-p (database-connection)
→ boolean
Test whether a database connection is still open.
method
connection-meta (database-connection)
→ hash-table
This method provides access to a hash table that is associated with the current database connection. When the connection is closed and re-opened this hash table is reset. The most obvious use for this is for storing information about the prepared statements that have been parsed for this connection.
method
connection-parameters (database-connection)
→ hash-table
This method returns a mapping (string to string) containing all the configuration parameters for the connection.
function
exec-query (database-connection query &optional (row-reader 'ignore-row-reader))
→ result
Sends the given query to the given connection, and interprets the results (if there are any) with the given row-reader. If the database returns information about the amount of rows effected, this is returned as a second value.
function prepare-query (database-connection name query)
Parse and plan the given query, and store it under the given name. Note that prepared statements are per-connection, so they can only be executed through the same connection that prepared them.
function
exec-prepared (database-connection name parameters &optional (row-reader 'ignore-row-reader))
→ result
Execute the prepared statement by the given name.
Parameters should be given as a list. Each value in this list
should be of a type that to-sql-string has been
specialised on. (Byte arrays will be passed in their binary form,
without being put through to-sql-string.) The result
of the executing the statement, if any, is interpreted by the
given row reader, and returned. Again,
the number or effected rows is optionally returned as a second
value.
method
to-sql-string (value)
→ (values string needs-escaping)
Convert a Lisp value to its textual unescaped SQL representation. Returns a second value indicating whether this value should be escaped if it is to be put directly into a query.
You can define to-sql-string methods
for your own datatypes if you want to be able to pass them to exec-prepared. When a
non-NIL second value is returned, this may be
T to indicate that the first value should simply be
escaped as a string, or a second string providing a type prefix
for the value. (This is used by S-SQL.)
When debugging, it can be helpful to inspect the
queries that are being sent to the database. Set this variable to
an output stream value (*standard-output*, for
example) to have CL-postgres log every query it makes.
CL-postgres knows how to convert commonly used PostgreSQL data types to Lisp values. This table shows the mapping:
| PostgreSQL | Lisp |
|---|---|
| smallint | integer |
| integer | integer |
| bigint | integer |
| numeric | ratio |
| real | float |
| double precision | double-float |
| boolean | boolean |
| varchar | string |
| text | string |
| bytea | (vector (unsigned-byte 8)) |
The mapping from PostgreSQL types (identified by OID numbers) to the functions that interpret them is kept in so-called SQL readtables. All types for which no reader is defined will be returned as string values containing their PostgreSQL representation.
This variable is used to choose the current readtable. For simple use, you will not have to touch this, but it is possible that code within a Lisp image requires different readers in different situations, in which case you can create separate read tables.
function
copy-sql-readtable (table)
→ readtable
Copies a given readtable.
function
default-sql-readtable ()
→ readtable
Returns the default readtable, containing only the readers defined by CL-postgres itself.
function set-sql-reader (oid function &key table binary-p)
Define a new reader for a given type.
table defaults to *sql-readtable*. The
reader function should take a single argument, a string, and
transform that into some kind of equivalent Lisp value. When
binary-p is true, the reader function is supposed to
directly read the binary representation of the value. In most
cases this is not recommended, but if you want to use it: provide
a function that takes a binary input stream and an integer (the
size of the value, in bytes), and reads the value from that
stream. Note that reading less or more bytes than the given size
will horribly break your connection.
function set-sql-datetime-readers (&key date timestamp timestamp-with-timezone time interval table)
Since there is no widely recognised standard way
of represenging dates and times in Common Lisp, and reading these
from string representation is clunky and slow, this function
provides a way to easily plug in binary readers for the
date, time, timestamp, and
interval types. It should be given functions with the
following signatures:
:date (days)days is the amount of days since January
1st, 2000.:timestamp (useconds):timestamp-with-timezone:timestamp, but for values of the
'timestamp with time zone' type (which PostgreSQL internally
stores exactly the same as regular timestamps).:time (useconds):interval (months days useconds)Row readers are a way to read and group the results of queries. Roughly, they are functions that perform the iteration over the rows and cells in the result, and do something with the returned values.
macro
row-reader ((fields) &body body)
→ function
Creates a row-reader, using the given name for the
variable. Inside the body this variable refers to a vector of
field descriptions. On top of that, two local functions are bound,
next-row and next-field. The first will
start reading the next row in the result, and returns a boolean
indicating whether there is another row. The second will read and
return one field, and should be passed the corresponding field
description from the fields argument as a parameter.
A row reader should take care to iterate over all
the rows in a result, and within each row iterate over all the
fields. This means it should contain an outer loop that calls
next-row, and every time next-row
returns T it should iterate over the fields vector
and call next-field for every field.
The definition of list-row-reader should
give you an idea what a row reader looks like:
(row-reader (fields)
(loop :while (next-row)
:collect (loop :for field :across fields
:collect (next-field field))))
Obviously, row readers should not do things with the database connection like, say, close it or start a new query, since it still reading out the results from the current query.
macro def-row-reader (name (fields) &body body)
The defun-like variant of row-reader: creates a row
reader and gives it a top-level function name.
method
field-name (field)
→ string
This can be used to get information about the fields read by a row reader. Given a field description, it returns the name the database associated with this column.
method
field-type (field)
→ oid
This extracts the PostgreSQL OID associated with this column. You can, if you really want to, query the pg_types table to find out more about the types denoted by OIDs.
function
list-row-reader (socket fields)
→ list
A row reader that builds a list of lists from the query results.
function
alist-row-reader (socket fields)
→ alist
A row reader that returns a list of alists, which associate column names with values.
function ignore-row-reader (socket fields)
A row reader that completely ignores the result of a query.
Opening or querying a database may raise errors. CL-postgres will wrap the errors that the server returns in a lisp condition, and raise conditions of the same type when it detects some problem itself. Socket errors are let through as they are.
The type of database-related conditions. For
errors that you may want to catch by type, the
cl-postgres-error package defines a bucket of
subtypes used for specific errors. See the
cl-postgres/package.lisp file for a list.
method
database-error-message (database-error)
→ string
A short message associated with this error.
method
database-error-detail (database-error)
→ string
A longer description of the problem, or
NIL if none is available.
method
database-error-code (database-error)
→ string
The error code PostgreSQL associated with this error, if any. See the PostgreSQL manual for their meaning.
method
database-error-query (database-error)
→ string
The query that led to this error, or
NIL if no query was involved.
method
database-error-cause (database-error)
→ condition
The condition that caused this error, or
NIL when it was not caused by another condition.
condition database-connection-error
Subtype of database-error. An error
of this type (or one of its subclasses) is signaled when a query
is attempted with a connection object that is no longer connected,
or a database connection becomes invalid during a query. Always
provides a :reconnect restart, which will cause the
library to make an attempt to restore the connection and re-try
the query.
The following shows an example use of this feature, a way to ensure that the first connection error causes a reconnect attempt, while others pass through as normal. A variation on this theme could continue trying to reconnect, with successively longer pauses.
(defun call-with-single-reconnect (fun)
(let ((reconnected nil))
(handler-bind
((database-connection-error
(lambda (err)
(when (not reconnected)
(setf reconnected t)
(invoke-restart :reconnect)))))
(funcall fun))))