Common Lisp Package: CL-POSTGRES

README:

FUNCTION

Public

CLOSE-DATABASE (CONNECTION)

Gracefully disconnect a database connection.

CONNECTION-META (CONNECTION)

Retrieves the meta field of a connection, the primary purpose of which is to store information about the prepared statements that exists for it.

DATABASE-ERROR-CONSTRAINT-NAME (ERR)

Given a database-error for an integrity violation, will attempt to extract the constraint name.

DATABASE-OPEN-P (CONNECTION)

Returns a boolean indicating whether the given connection is currently connected.

EXEC-PREPARED (CONNECTION NAME PARAMETERS &OPTIONAL (ROW-READER 'IGNORE-ROW-READER))

Execute a previously prepared query with the given parameters, apply a row-reader to the result.

EXEC-QUERY (CONNECTION QUERY &OPTIONAL (ROW-READER 'IGNORE-ROW-READER))

Execute a query string and apply the given row-reader to the result.

OPEN-DATABASE (DATABASE USER PASSWORD HOST &OPTIONAL (PORT 5432) (USE-SSL NO) (SERVICE postgres))

Create and connect a database object. use-ssl may be :no, :yes, or :try.

PREPARE-QUERY (CONNECTION NAME QUERY)

Prepare a query string and store it under the given name.

REOPEN-DATABASE (CONN)

Reconnect a disconnected database connection.

SET-SQL-READER (OID FUNCTION &KEY (TABLE *SQL-READTABLE*) BINARY-P)

Add an sql reader to a readtable. When the reader is not binary, it is wrapped by a function that will read the string from the socket.

WAIT-FOR-NOTIFICATION (CONNECTION)

Perform a blocking wait for asynchronous notification. Return the channel string, the payload and notifying pid as multiple values.

Undocumented

ALIST-ROW-READER (G546 FIELDS)

CLOSE-DB-WRITER (SELF &KEY (ABORT T))

COPY-SQL-READTABLE (&OPTIONAL (TABLE *SQL-READTABLE*))

DB-WRITE-ROW (SELF ROW &OPTIONAL (DATA (PREPARE-ROW SELF ROW)))

DEFAULT-SQL-READTABLE

IGNORE-ROW-READER (G664 FIELDS)

LIST-ROW-READER (G584 FIELDS)

LOG-QUERY (QUERY TIME-UNITS)

OPEN-DB-WRITER (DB-SPEC TABLE COLUMNS)

SET-SQL-DATETIME-READERS (&KEY DATE TIMESTAMP TIMESTAMP-WITH-TIMEZONE INTERVAL TIME (TABLE *SQL-READTABLE*))

VECTOR-ROW-READER (G622 FIELDS)

Private

AUTHENTICATE (SOCKET CONN)

Try to initiate a connection. Caller should close the socket if this raises a condition.

BIND-MESSAGE (SOCKET NAME RESULT-FORMATS PARAMETERS)

Bind a prepared statement, ask for the given formats, and pass the given parameters, that can be either string or byte vector. (vector (unsigned-byte 8)) parameters will be sent as binary data, useful for binding data for binary long object columns.

BUILD-ROW-READER (FUNCTION-FORM FIELDS BODY)

Helper for the following two macros.

BYTES-TO-HEX-STRING (BYTES)

Convert an array of 0-255 numbers into the corresponding string of (lowercase) hex codes.

ENSURE-CONNECTION (CONN)

Used to make sure a connection object is connected before doing anything with it.

ESCAPE-BYTES (BYTES)

Escape an array of octets in PostgreSQL's horribly inefficient textual format for binary data.

FORMATS-TO-BYTES (FORMATS)

Formats have to be passed as arrays of 2-byte integers, with 1 indicating binary and 0 indicating plain text.

GET-ERROR (SOCKET)

Read an error message from the socket and raise the corresponding database-error condition.

GET-NOTIFICATION (SOCKET)

Read an asynchronous notification message from the socket and signal a condition for it.

GET-WARNING (SOCKET)

Read a warning from the socket and emit it.

INITIATE-CONNECTION (CONN)

Check whether a connection object is connected, try to connect it if it isn't.

INITIATE-SSL (SOCKET REQUIRED)

Initiate SSL handshake with the Posgres server, and wrap the socket in an SSL stream. When require is true, an error will be raised when the server does not support SSL.

INTERPRET-AS-TEXT (STREAM SIZE)

This interpreter is used for types that we have no specific interpreter for -- it just reads the value as a string. (Values of unknown types are passed in text form.)

INTERPRET-USEC-BITS (BITS)

Decode a 64 bit time-related value based on the timestamp format used. Correct for sign bit when using integer format.

LOOK-FOR-ROW (SOCKET)

Read server messages until either a new row can be read, or there are no more results. Return a boolean indicating whether any more results are available, and, if available, stores the amount of effected rows in *effected-rows*. Also handle getting out of copy-in/copy-out states (which are not supported).

MD5-PASSWORD (PASSWORD USER SALT)

Apply the hashing that PostgreSQL expects to a password.

READ-BYTE-DELIMITED (SOCKET)

Read the fields of a null-terminated list of byte + string values and put them in an alist.

READ-BYTES (SOCKET LENGTH)

Read a byte array of the given length from a stream.

READ-FIELD-DESCRIPTIONS (SOCKET)

Read the field descriptions for a query result and put them into an array of field-description objects.

READ-SIMPLE-STR (SOCKET)

Read a null-terminated string from a stream. Interprets it as ASCII.

READ-STR (SOCKET)

Read a null-terminated string from a stream. Takes care of encoding when UTF-8 support is enabled.

SEND-EXECUTE (SOCKET NAME PARAMETERS ROW-READER)

Execute a previously parsed query, and apply the given row-reader to the result.

SEND-PARSE (SOCKET NAME QUERY)

Send a parse command to the server, giving it a name.

SEND-QUERY (SOCKET QUERY ROW-READER)

Send a query to the server, and apply the given row-reader to the results.

SKIP-BYTES (SOCKET LENGTH)

Skip a given number of bytes in a binary stream.

SKIP-STR (SOCKET)

Skip a null-terminated string.

TERMINATE-CONNECTION (SOCKET)

Close a connection, notifying the server.

TRY-TO-SYNC (SOCKET SYNC-SENT)

Try to re-synchronize a connection by sending a sync message if it hasn't already been sent, and then looking for a ReadyForQuery message.

TYPE-INTERPRETER (OID)

Returns a pair representing the interpretation rules for this type. The car is a boolean indicating whether the type should be fetched as binary, and the cdr is a function that will read the value from the socket and build a Lisp value from it.

WRITE-BYTES (SOCKET BYTES)

Write a byte-array to a stream.

WRITE-STR (SOCKET STRING)

Write a null-terminated string to a stream (encoding it when UTF-8 support is enabled.).

Undocumented

COPIER-WRITE-SEQUENCE (S VECTOR)

COPIER-WRITE-VALUE (S VAL)

COPY-DATA-MESSAGE (SOCKET DATA)

COPY-DONE-MESSAGE (G930)

COPY-FAIL-MESSAGE (G972 REASON)

COPY-QUERY (SELF)

DESCRIBE-PREPARED-MESSAGE (G846 NAME)

ENC-BYTE-LENGTH (SEQUENCE)

ENC-READ-STRING (INPUT &KEY NULL-TERMINATED (BYTE-LENGTH -1))

ENC-STRING-BYTES (STRING &KEY NULL-TERMINATE)

ENC-WRITE-STRING (STRING OUTPUT &KEY NULL-TERMINATE)

ENSURE-SOCKET-IS-CLOSED (SOCKET &KEY ABORT)

FLUSH-MESSAGE (G894)

GSS-AUTH-BUFFER-MESSAGE (G582 BUF)

INITIALIZE-COPIER (SELF)

INTEGER-READER-NAME (BYTES SIGNED)

INTEGER-WRITER-NAME (BYTES SIGNED)

MD5-PASSWORD-MESSAGE (G563 PASSWORD USER SALT)

PARSE-MESSAGE (G641 NAME QUERY)

PLAIN-PASSWORD-MESSAGE (G87 PASSWORD)

QUERY-MESSAGE (G599 QUERY)

READ-ARRAY-VALUE (TRANSFORM)

READ-INT1 (SOCKET)

READ-INT2 (SOCKET)

READ-INT4 (SOCKET)

READ-INT8 (SOCKET)

READ-UINT1 (SOCKET)

READ-UINT2 (SOCKET)

READ-UINT4 (SOCKET)

READ-UINT8 (SOCKET)

SB-SOCKET-CONNECT (PORT HOST)

SB-UNIX-SOCKET-CONNECT (PORT)

SEND-COPY-DONE (SOCKET)

SEND-COPY-START (SOCKET QUERY)

SET-DATE-READER (F TABLE)

SET-INTERVAL-READER (F TABLE)

SET-USEC-READER (OID F TABLE)

SIMPLE-BIND-MESSAGE (G681 FORMATS)

SIMPLE-DESCRIBE-MESSAGE (G824)

SIMPLE-EXECUTE-MESSAGE (G868)

SIMPLE-PARSE-MESSAGE (G616 QUERY)

SSL-REQUEST-MESSAGE (G41)

STARTUP-MESSAGE (G58 USER DATABASE)

SYNC-MESSAGE (G906)

TERMINATE-MESSAGE (G918)

UNIX-SOCKET-PATH (PORT)

UPDATE-PARAMETER (SOCKET)

WRAP-SOCKET-ERROR (ERR)

WRITE-INT1 (SOCKET VALUE)

WRITE-INT2 (SOCKET VALUE)

WRITE-INT4 (SOCKET VALUE)

WRITE-QUOTED (STRING OUT)

WRITE-RATIONAL-AS-FLOATING-POINT (NUMBER STREAM DIGIT-LENGTH-LIMIT)

WRITE-UINT1 (SOCKET VALUE)

WRITE-UINT2 (SOCKET VALUE)

WRITE-UINT4 (SOCKET VALUE)

MACRO

Public

DEF-ROW-READER (NAME (FIELDS) &BODY BODY)

Create a row reader, as in the row-reader macro, and assign a name to it.

ROW-READER ((FIELDS) &BODY BODY)

Create a row-reader, using the given name for the fields argument and the given body for reading the rows. A row reader is a function that is used to do something with the results of a query. It has two local functions: next-row and next-field, the first should be called once per row and will return a boolean indicating whether there are any more rows, the second should be called once for every element in the fields vector, with that field as argument, to read a single value in a row. See list-row-reader in public.lisp for an example.

Private

BINARY-READER (FIELDS &BODY VALUE)

A slightly convoluted macro for defining interpreter functions. It allows two forms. The first is to pass a single type identifier, in which case a value of this type will be read and returned directly. The second is to pass a list of lists containing names and types, and then a body. In this case the names will be bound to values read from the socket and interpreted as the given types, and then the body will be run in the resulting environment. If the last field is of type bytes, string, or uint2s, all remaining data will be read and interpreted as an array of the given type.

DEFINE-INTERPRETER (OID NAME FIELDS &BODY VALUE)

Shorthand for defining binary readers.

DEFINE-MESSAGE (NAME ID (&REST ARGLIST) &BODY PARTS)

This macro synthesizes a function to send messages of a specific type. It takes care of the plumbing -- calling writer functions on a stream, keeping track of the length of the message -- so that the message definitions themselves stay readable.

INTEGER-READER (BYTES)

Create a function to read integers from a binary stream.

INTEGER-WRITER (BYTES)

Create a function to write integers to a binary stream.

MESSAGE-CASE (SOCKET &BODY CLAUSES)

Helper macro for reading messages from the server. A list of cases (characters that identify the message) can be given, each with a body that handles the message, or the keyword :skip to skip the message. Cases for error and warning messages are always added. The body may contain an initial parameter of the form :LENGTH-SYM SYMBOL where SYMBOL is a symbol to which the remaining length of the packet is bound. This value indicates the number of bytes that have to be read from the socket.

RETURNING-EFFECTED-ROWS (VALUE &BODY BODY)

Computes a value, then runs a body, then returns, as multiple values, that value and the amount of effected rows, if any (see *effected rows*).

USING-CONNECTION (CONNECTION &BODY BODY)

This is used to prevent a row-reader from recursively calling some query function. Because the connection is still returning results from the previous query when a row-reading is being executed, starting another query will not work as expected (or at all, in general). This might also raise an error when you are using a single database connection from multiple threads, but you should not do that at all. Also binds *timestamp-format* and *connection-params*, which might be needed by the code interpreting the query results.

WITH-RECONNECT-RESTART (CONNECTION &BODY BODY)

When, inside the body, an error occurs that breaks the connection socket, a condition of type database-connection-error is raised, offering a :reconnect restart.

WITH-SYNCING (&BODY BODY)

Macro to wrap a block in a handler that will try to re-sync the connection if something in the block raises a condition. Not hygienic at all, only used right below here.

Undocumented

WITH-QUERY ((QUERY) &BODY BODY)

GENERIC-FUNCTION

Public

TO-SQL-STRING (ARG)

Turn a lisp value into a string containing its SQL representation. Returns an optional second value that indicates whether the string should be escaped before being put into a query.

Undocumented

DATABASE-ERROR-CAUSE (CONDITION)

DATABASE-ERROR-CODE (CONDITION)

DATABASE-ERROR-DETAIL (CONDITION)

DATABASE-ERROR-MESSAGE (CONDITION)

SETFDATABASE-ERROR-MESSAGE (NEW-VALUE CONDITION)

DATABASE-ERROR-QUERY (CONDITION)

POSTGRESQL-NOTIFICATION-CHANNEL (CONDITION)

SETFPOSTGRESQL-NOTIFICATION-CHANNEL (NEW-VALUE CONDITION)

POSTGRESQL-NOTIFICATION-PAYLOAD (CONDITION)

SETFPOSTGRESQL-NOTIFICATION-PAYLOAD (NEW-VALUE CONDITION)

POSTGRESQL-NOTIFICATION-PID (CONDITION)

SETFPOSTGRESQL-NOTIFICATION-PID (NEW-VALUE CONDITION)

Private

Undocumented

DATABASE-ERROR-POSITION (CONDITION)

PREPARE-ROW (SELF ROW)

SLOT-ACCESSOR

Public

Undocumented

CONNECTION-PARAMETERS (OBJECT)

SETFCONNECTION-PARAMETERS (NEW-VALUE OBJECT)

FIELD-NAME (OBJECT)

SETFFIELD-NAME (NEW-VALUE OBJECT)

FIELD-TYPE (OBJECT)

SETFFIELD-TYPE (NEW-VALUE OBJECT)

Private

Undocumented

CONNECTION-AVAILABLE (OBJECT)

SETFCONNECTION-AVAILABLE (NEW-VALUE OBJECT)

CONNECTION-DB (OBJECT)

CONNECTION-HOST (OBJECT)

CONNECTION-PASSWORD (OBJECT)

CONNECTION-PORT (OBJECT)

CONNECTION-SERVICE (OBJECT)

SETFCONNECTION-SERVICE (NEW-VALUE OBJECT)

CONNECTION-SOCKET (OBJECT)

SETFCONNECTION-SOCKET (NEW-VALUE OBJECT)

CONNECTION-TIMESTAMP-FORMAT (OBJECT)

SETFCONNECTION-TIMESTAMP-FORMAT (NEW-VALUE OBJECT)

CONNECTION-USE-SSL (OBJECT)

CONNECTION-USER (OBJECT)

COPIER-COLUMNS (OBJECT)

COPIER-COUNT (OBJECT)

SETFCOPIER-COUNT (NEW-VALUE OBJECT)

COPIER-DATABASE (OBJECT)

COPIER-TABLE (OBJECT)

FIELD-BINARY-P (OBJECT)

SETFFIELD-BINARY-P (NEW-VALUE OBJECT)

FIELD-INTERPRETER (OBJECT)

SETFFIELD-INTERPRETER (NEW-VALUE OBJECT)

VARIABLE

Public

*SQL-READTABLE*

The exported special var holding the current read table, a hash mapping OIDs to (binary-p . interpreter-function) pairs.

*SSL-CERTIFICATE-FILE*

When set to a filename, this file will be used as client certificate for SSL connections.

*SSL-KEY-FILE*

When set to a filename, this file will be used as client key for SSL connections.

*UNIX-SOCKET-DIR*

Directory where the Unix domain socket for Postgres be found.

Undocumented

*QUERY-CALLBACK*

*QUERY-LOG*

*SILENTLY-TRUNCATE-RATIONALS*

Private

*CONNECTION-PARAMS*

Bound to the current connection's parameter table when executing a query.

*DEFAULT-SQL-READTABLE*

A copy of the default readtable that client code can fall back on.

*TIMESTAMP-FORMAT*

This is used to communicate the format (integer or float) used for timestamps and intervals in the current connection, so that the interpreters for those types know how to parse them.

Undocumented

*CLIENT-ENCODING*

*CURRENT-QUERY*

*EFFECTED-ROWS*

*OPTIMIZE*

CLASS

Public

DATABASE-CONNECTION

Representatino of a database connection. Contains login information in order to be able to automatically re-establish a connection when it is somehow closed.

Private

FIELD-DESCRIPTION

Description of a field in a query result.

Undocumented

BULK-COPIER

CONDITION

Public

DATABASE-CONNECTION-ERROR

Conditions of this type are signalled when an error occurs that breaks the connection socket. They offer a :reconnect restart.

DATABASE-CONNECTION-LOST

Raised when a query is initiated on a disconnected connection object.

DATABASE-ERROR

This is the condition type that will be used to signal virtually all database-related errors (though in some cases socket errors may be raised when a connection fails on the IP level).

DATABASE-SOCKET-ERROR

Used to wrap stream-errors and socket-errors, giving them a database-connection-error superclass.

Undocumented

POSTGRESQL-NOTIFICATION

POSTGRESQL-WARNING

Private

PROTOCOL-ERROR

This is raised if something really unexpected happens in the communcation with the server. Should only happen in case of a bug or a connection to something that is not a (supported) PostgreSQL server at all.

CONSTANT

Private

Undocumented

+SECONDS-IN-DAY+

+START-OF-2000+