Common Lisp Package: POSTMODERN

README:

FUNCTION

Public

!DAO-DEF

Used inside a deftable form. Define this table using the corresponding DAO class' slots.

!FOREIGN (TARGET FIELDS &REST TARGET-FIELDS/ON-DELETE/ON-UPDATE/DEFERRABLE/INITIALLY-DEFERRED)

Used inside a deftable form. Define a foreign key on this table. Pass a table the index refers to, a list of fields or single field in *this* table, and, if the fields have different names in the table referred to, another field or list of fields for the target table, or :primary-key to indicate that the other table's primary key should be referenced.

!INDEX (&REST FIELDS)

Used inside a deftable form. Define an index on the defined table.

!UNIQUE-INDEX (&REST FIELDS)

Used inside a deftable form. Define a unique index on the defined table.

ABORT-TRANSACTION (TRANSACTION)

Immediately abort an open transaction.

CALL-WITH-CONNECTION (SPEC THUNK)

Binds *database* to a new connection, as specified by the spec argument, which should be a list of arguments that can be passed to connect, and runs the function given as a second argument with that database.

CLEAR-CONNECTION-POOL

Disconnect and remove all connections in the connection pool.

COMMIT-TRANSACTION (TRANSACTION)

Immediately commit an open transaction.

CONNECT (DATABASE USER PASSWORD HOST &KEY (PORT 5432) POOLED-P (USE-SSL *DEFAULT-USE-SSL*) (SERVICE postgres))

Create and return a database connection.

CONNECT-TOPLEVEL (DATABASE USER PASSWORD HOST &KEY (PORT 5432) (USE-SSL *DEFAULT-USE-SSL*))

Set *database* to a new connection. Use this if you only need one connection, or if you want a connection for debugging from the REPL.

CONNECTED-P (DATABASE)

Test whether a database connection is still connected.

CREATE-ALL-TABLES

Create all defined tables.

CREATE-PACKAGE-TABLES (PACKAGE)

Create all tables whose identifying symbol is interned in the given package.

CREATE-TABLE (NAME)

Create a defined table.

DAO-TABLE-DEFINITION (TABLE)

Generate the appropriate CREATE TABLE query for this class.

DATABASE-ERROR-CONSTRAINT-NAME (ERR)

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

DISCONNECT-TOPLEVEL

Disconnect *database*.

LIST-SEQUENCES (&OPTIONAL STRINGS-P)

Return a list of the sequences in a database. Turn them into keywords if strings-p is not true.

LIST-TABLES (&OPTIONAL STRINGS-P)

Return a list of the tables in a database. Turn them into keywords if strings-p is not true.

LIST-VIEWS (&OPTIONAL STRINGS-P)

Return a list of the views in a database. Turn them into keywords if strings-p is not true.

RELEASE-SAVEPOINT (SAVEPOINT)

Immediately release a savepoint, commiting its results.

ROLLBACK-SAVEPOINT (SAVEPOINT)

Immediately roll back a savepoint, aborting it results.

SAVE-DAO (DAO)

Try to insert the content of a DAO. If this leads to a unique key violation, update it instead.

SEQUENCE-EXISTS-P (SEQUENCE)

Check whether a sequence exists. Takes either a string or a symbol for the sequence name.

SEQUENCE-NEXT (SEQUENCE)

Shortcut for getting the next value from a sequence.

SQL-ESCAPE-STRING (STRING &OPTIONAL PREFIX)

Escape string data so it can be used in a query.

TABLE-DESCRIPTION (TABLE &OPTIONAL SCHEMA-NAME)

Return a list of (name type null-allowed) lists for the fields of a table. If SCHEMA-NAME is specified, only fields from that schema are returned.

TABLE-EXISTS-P (TABLE)

Check whether a table exists. Takes either a string or a symbol for the table name.

VIEW-EXISTS-P (VIEW)

Check whether a view exists. Takes either a string or a symbol for the view name.

Undocumented

!UNIQUE (TARGET-FIELDS &KEY DEFERRABLE INITIALLY-DEFERRED)

COALESCE (&REST ARGS)

DAO-TABLE-NAME (CLASS)

SAVE-DAO/TRANSACTION (DAO)

SQL-COMPILE (FORM)

SQL-ERROR (CONTROL &REST ARGS)

Private

BUILD-DAO-METHODS (CLASS)

Synthesise a number of methods for a newly defined DAO class. (Done this way because some of them are not defined in every situation, and each of them needs to close over some pre-computed values.)

DAO-COLUMN-SLOTS (CLASS)

Enumerate the slots in a class that refer to table rows.

DAO-ROW-READER (CLASS)

Defines a row-reader for objects of a given class.

DAO-SUPERCLASSES (CLASS)

Build a list of superclasses of a given class that are DAO classes.

ENSURE-PREPARED (CONNECTION ID QUERY)

Make sure a statement has been prepared for this connection.

GENERATE-PREPARED (FUNCTION-FORM QUERY FORMAT)

Helper macro for the following two functions.

GET-FROM-POOL (TYPE)

Get a database connection from the specified pool, returns nil if no connection was available.

NEXT-STATEMENT-ID

Provide unique statement names.

REAL-QUERY (QUERY)

Used for supporting both plain string queries and S-SQL constructs. Looks at the argument at compile-time and wraps it in (sql ...) if it looks like an S-SQL query.

TO-IDENTIFIER (NAME)

Used to allow both strings and symbols as identifier - converts symbols to string with the S-SQL rules.

Undocumented

%EVAL (CODE)

ADD-TABLE-DEFINITION (SYMBOL FUNC)

COLUMN-ROW-READER (G91 FIELDS)

DAO-COLUMN-FIELDS (CLASS)

DAO-SPEC-FOR-FORMAT (FORMAT)

FLAT-TABLE-NAME (&OPTIONAL (TABLE *TABLE-NAME*))

QUERY-DAO% (TYPE QUERY &REST ARGS)

READER-FOR-FORMAT (FORMAT)

SYMBOL-ALIST-ROW-READER (G0 FIELDS)

SYMBOL-PLIST-ROW-READER (G44 FIELDS)

MACRO

Public

DEFPREPARED (NAME QUERY &OPTIONAL (FORMAT ROWS))

Like perpare, but gives the function a name instead of returning it.

DEFPREPARED-WITH-NAMES (NAME (&REST ARGS) (QUERY &REST QUERY-ARGS) &OPTIONAL (FORMAT ROWS))

Like defprepared, but with lambda list for statement arguments.

DEFTABLE (NAME &BODY DEFINITIONS)

Define a table. name can be either a symbol or a (symbol string) list. In the first case, the table name is derived from the symbol by S-SQL's rules, in the second case, the name is given explicitly. The body of definitions can contain anything that evaluates to a string, as well as S-SQL expressions. In this body, the variables *table-name* and *table-symbol* are bound to the relevant values.

DOQUERY (QUERY (&REST NAMES) &BODY BODY)

Iterate over the rows in the result of a query, binding the given names to the results and executing body for every row. Query can be a string, an s-sql query, or a list starting with one of those, followed by the arguments to parameterize the query with.

EXECUTE (QUERY &REST ARGS)

Execute a query, ignore the results.

PREPARE (QUERY &OPTIONAL (FORMAT ROWS))

Wraps a query into a function that will prepare it once for a connection, and then execute it with the given parameters. The query should contain a placeholder ($1, $2, etc) for every parameter.

QUERY (QUERY &REST ARGS/FORMAT)

Execute a query, optionally with arguments to put in the place of $X elements. If one of the arguments is a known result style or a class name, it specifies the format in which the results should be returned.

QUERY-DAO (TYPE QUERY &REST ARGS)

Execute a query and return the result as daos of the given type. The fields returned by the query must match the slots of the dao, both by type and by name.

REGISTER-SQL-OPERATORS (ARITY &REST NAMES)

Define simple operators. Arity is one of :unary (like 'not'), :unary-postfix (the operator comes after the operand), :n-ary (like '+': the operator falls away when there is only one operand), :2+-ary (like '=', which is meaningless for one operand), or :n-or-unary (like '-', where the operator is kept in the unary case). After the arity follow any number of operators, either just a keyword, in which case the downcased symbol name is used as the operator, or a two-element list containing a keyword and a name string.

SELECT-DAO (TYPE &OPTIONAL (TEST T) &REST ORDERING)

Select daos for the rows in its table for which the given test holds, order them by the given criteria.

SQL (FORM)

Compile form to an sql expression as far as possible.

WITH-CONNECTION (SPEC &BODY BODY)

Locally establish a database connection, and bind *database* to it.

WITH-SAVEPOINT (NAME &BODY BODY)

Execute the body within a savepoint, releasing savepoint when the body exits normally, and rolling back otherwise. NAME is both the variable that can be used to release or rolled back before the body unwinds, and the SQL name of the savepoint.

WITH-TRANSACTION ((&OPTIONAL NAME) &BODY BODY)

Execute the body within a database transaction, committing when the body exits normally, and aborting otherwise. An optional name can be given to the transaction, which can be used to force a commit or abort before the body unwinds.

Undocumented

DEFINE-DAO-FINALIZATION (((DAO-NAME CLASS) &REST KEYWORD-ARGS) &BODY BODY)

WITH-COLUMN-WRITERS ((&REST DEFS) &BODY BODY)

Private

MAKE-EXISTS-QUERY (RELKIND NAME)

Helper macro for the functions that check whether an object exists.

MAKE-LIST-QUERY (RELKIND)

Helper macro for the functions that list tables, sequences, and views.

WITH-POOL-LOCK (&BODY BODY)

Aquire a lock for the pool when evaluating body (if thread support is present).

Undocumented

ALL-ROWS (FORM)

SINGLE-ROW (FORM)

SINGLE-ROW! (FORM)

GENERIC-FUNCTION

Public

DAO-EXISTS-P (DAO)

Return a boolean indicating whether the given dao exists in the database.

DELETE-DAO (DAO)

Delete the given dao from the database.

DISCONNECT (DATABASE)

Close a database connection. Returns it to a pool if it is a pooled connection.

GET-DAO (TYPE &REST ARGS)

Get the object corresponding to the given primary key, or return nil if it does not exist.

INSERT-DAO (DAO)

Insert the given object into the database.

MAKE-DAO (TYPE &REST ARGS &ALLOW-OTHER-KEYS)

Make the instance of the given class and insert it into the database

RECONNECT (DATABASE)

Reconnect a database connection.

SQL-ESCAPE (ARG)

Get the representation of a Lisp value so that it can be used in a query.

UPDATE-DAO (DAO)

Update the object's representation in the database with the values in the given instance.

UPSERT-DAO (DAO)

Update or insert the given dao. If its primary key is already in the database and all slots are bound, an update will occur. Otherwise it tries to insert it.

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)

Private

FETCH-DEFAULTS (OBJECT)

Used to fetch the default values of an object on creation.

SLOT-ACCESSOR

Public

Undocumented

DAO-KEYS (OBJECT)

Private

Undocumented

COLUMN-DEFAULT (OBJECT)

COLUMN-TYPE (OBJECT)

CONNECTION-POOL-TYPE (OBJECT)

SETFCONNECTION-POOL-TYPE (NEW-VALUE OBJECT)

DAO-COLUMN-MAP (OBJECT)

DIRECT-KEYS (OBJECT)

GHOST (OBJECT)

SAVEPOINT-CONNECTION (OBJECT)

SAVEPOINT-NAME (OBJECT)

SAVEPOINT-OPEN-P (OBJECT)

SETFSAVEPOINT-OPEN-P (NEW-VALUE OBJECT)

SLOT-COLUMN (OBJECT)

SLOT-SQL-NAME (OBJECT)

TRANSACTION-CONNECTION (OBJECT)

TRANSACTION-OPEN-P (OBJECT)

SETFTRANSACTION-OPEN-P (NEW-VALUE OBJECT)

VARIABLE

Public

*DATABASE*

Special holding the current database. Most functions and macros operating on a database assume this contains a connected database.

*ESCAPE-SQL-NAMES-P*

Setting this to T will make S-SQL add double quotes around identifiers in queries. Setting it :auto will turn on this behaviour only for reserved words.

*MAX-POOL-SIZE*

The maximum amount of connection that will be kept in a single pool, or NIL for no maximum.

Undocumented

*DEFAULT-USE-SSL*

*IGNORE-UNKNOWN-COLUMNS*

Private

*CONNECTION-POOLS*

Maps pool specifiers to lists of pooled connections.

*CUSTOM-COLUMN-WRITERS*

A hook for locally overriding/adding behaviour to DAO row readers. Should be an alist mapping strings (column names) to symbols or functions. Symbols are interpreted as slot names that values should be written to, functions are called with the new object and the value as arguments.

*DIRECT-COLUMN-SLOT*

This is used to communicate the fact that a slot is a column to effective-slot-definition-class.

*POOL-LOCK*

A lock to prevent multiple threads from messing with the connection pool at the same time.

*RESULT-STYLES*

Mapping from keywords identifying result styles to the row-reader that should be used and whether all values or only one value should be returned.

*TABLES*

Unexported ordered list containing the known table definitions.

CLASS

Public

DAO-CLASS

Metaclass for database-access-object classes.

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.

Undocumented

REAL

Private

DIRECT-COLUMN-SLOT

Type of slots that refer to database columns.

POOLED-DATABASE-CONNECTION

Type for database connections that are pooled. Stores the arguments used to create it, so different pools can be distinguished.

SAVEPOINT-HANDLE

Simple box type for storing the state and the associated database connection of a savepoint.

TRANSACTION-HANDLE

Simple box type for storing the status and the associated database connection of a transaction. When open-p is nil, the transaction has been aborted or committed.

Undocumented

EFFECTIVE-COLUMN-SLOT

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-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).

Undocumented

SQL-ERROR (CONTROL &REST ARGS)