Driver API

(interface driver ...)

The interface implemented by database drivers.

(sql-symbol [sym symbol?]) → string?

Converts a symbol into a snippet of SQL source that can be used as an identifier.

Default implementation: The symbol is pre- and postfixed with the string "`". If the symbol already contains that character, an exception is thrown.

(make-sql-genparam) → (-> string?)

Creates a procedure that returns a fresh placeholder for a query parameter every time it is invoked.

Default implementation: The returned procedure constantly answers "?".

(connect [options list?]) → any/c

Establishes a database connection given an association list of options. Returns any token the driver sees fit.

(disconnect [db any/c]) → void?

Closes a database connection given a token returned by connect.

Default implementation: Does nothing.

(with-transaction [db any/c] [thunk (-> any/c)]) → any/c

Invokes thunk within the dynamic extent of a transaction on the given database and returns whatever thunk returns.

Default implementation: Invokes thunk without any special precautions.

(prepare [db any/c] [sql string?]) → any/c

Compiles SQL source code into a statement. Returns any token the driver sees fit.

(forget [stmt any/c]) → void?

Destroys a prepared statement.

Default implementation: Does nothing.

(row-length [row any/c]) → integer?

Determines the length of a result row.

(column-name [row any/c] [idx integer?]) → (or/c symbol? #f)

Determines the name of a result column.

Default implementation: Constantly returns #f.

(column-value [row any/c] [idx integer?]) → any/c

Extracts the value of a result column.

(rows-fold [kons (-> any/c any/c any/c)] [knil any/c] [stmt any/c] [args vector?]) → any/c

Binds query parameters and iterates over result rows. The row tokens passed to kons must be suitable to be handed on to the row or column accessor procedures.

Should be prepared to be interrupted in coroutine fashion.

Support Procedures

(select-driver [scheme symbol?]) → driver?

Returns a driver registered for the given URI scheme.

(register-driver! [scheme symbol?] [driver driver?]) → void?

Registers a driver for the given URI scheme.

(db-error [location symbol?] [message string?] [argument any/c] ...) → any
(db-error [message string?] [argument any/c] ...) → any

Behaves like the procedure error, but raises a condition of kind (exn db).

(with-db-errors [kind symbol?] [thunk (-> any/c)]) → any/c

Invokes thunk with an exception handler that turns any condition of the given kind into a composition condition with the additional kind db and then re-raises any exception.