The ISession class describes a database session to a particular DBMS. Oracle has its own Session object, SQLite has its own session object (which maintains the connection handle to the database engine and other related stuff). Session objects for different databases normally have different types -- yet they all belong to the class ISession so we can do generic operations like commit, execDDL, etc. in a database-independent manner.

A wrapper around the action to open the database. That wrapper is not exported to the end user. The only reason for the wrapper is to guarantee that the only thing to do with the result of connect function is to pass it out directly to withSession.

Typeable constraint is to prevent the leakage of Session and other marked objects.

Persistent database connections. This issue has been brought up by Shanky Surana. The following design is inspired by that exchange.

Perform an action as a transaction: commit afterwards, unless there was an exception, in which case rollback.

DDL operations don't manipulate data, so we return no information. If there is a problem, an exception will be raised.

Returns the number of rows affected.

Allows arbitrary actions to be run the DBM monad. The back-end developer must supply instances of EnvInquiry, which is hidden away in Database.InternalEnumerator. An example of this is LastInsertRowid.

A show for DBExceptions.

This simple handler reports the error to stdout and swallows it i.e. it doesn't propagate.

This handler reports the error and propagates it (usually to force the program to halt).

Same as reportRethrow, but you can prefix some text to the error (perhaps to indicate which part of your program raised it).

Catch DBExceptions thrown in the DBM monad.

If you want to trap a specific error number, use this. It passes anything else up.

Analogous to catchDBError, but ignores specific errors instead (propagates anything else).

Throw a DBException. It's just a type-specific throwDyn.

Prepare a statement and run a DBM action over it. This gives us the ability to re-use a statement, for example by passing different bind values for each execution.

Applies a prepared statement to bind variables to get a bound statement, which is passed to the provided action. Note that by the time it is passed to the action, the query or command has usually been executed. A bound statement would normally be an instance of Statement, so it can be passed to doQuery in order to process the result-set, and also an instance of Command, so that we can write re-usable DML statements (inserts, updates, deletes).

Statement defines the API for query objects i.e. which types can be queries.

Command is not a query: command deletes or updates rows, creates/drops tables, or changes database state. executeCommand returns the number of affected rows (or 0 if DDL i.e. not DML).

This type is not visible to the end user (cf. ConnectA). It forms a private `communication channel' between Database.Enumerator and a back end.

The binding object (bo) below is very abstract, on purpose. It may be |IO a|, it may be String, it may be a function, etc. The binding object can hold the result of marshalling, or bo can hold the current counter, etc. Different databases do things very differently: compare PostgreSQL and the Stub (which models Oracle).

The class DBBind is not used by the end-user. It is used to tie up low-level database access and the enumerator. A database-specific library must provide a set of instances for DBBind. The latter are the dual of DBType.

This is really just a wrapper that lets us write lists of heterogenous bind values e.g. [bindP "string", bindP (0::Int), ...]

The class IQuery describes the class of query objects. Each database (that is, each Session object) has its own Query object. We may assume that a Query object includes (at least, conceptually) a (pointer to) a Session object, so a Query object determines the Session object. A back-end provides an instance (or instances) of IQuery. The end user never seens the IQuery class (let alone its methods).

The left-fold interface.

A 'buffer' means a column buffer: a data structure that points to a block of memory allocated for the values of one particular column. Since a query normally fetches a row of several columns, we typically deal with a list of column buffers. Although the column data are typed (e.g., Integer, CalendarDate, etc), column buffers hide that type. Think of the column buffer as Dynamics. The class DBType below describes marshalling functions, to fetch a typed value out of the 'untyped' columnBuffer.

The class DBType is not used by the end-user. It is used to tie up low-level database access and the enumerator. A database-specific library must provide a set of instances for DBType.

IterResult and IterAct give us some type sugar. Without them, the types of iteratee functions become quite unwieldy.

cursorIsEOF's return value tells you if there are any more rows or not. If you call cursorNext when there are no more rows, a DBNoData exception is thrown. Cursors are automatically closed and freed when:

Returns the results fetched so far, processed by iteratee function.

Advance the cursor. Returns the cursor. The return value is usually ignored.

Ensures cursor resource is properly tidied up in exceptional cases. Propagates exceptions after closing cursor. The Typeable constraint is to prevent cursors and other marked values (like cursor computations) from escaping.

Useful utility function, for SQL weenies.

Another useful utility function. Use this to return a value from an iteratee function (the one passed to doQuery). Note that you should probably nearly always use the strict version.

A strict version. This is recommended unless you have a specific need for laziness, as the lazy version will gobble stack and heap. If you have a large result-set (in the order of 10-100K rows or more), it is likely to exhaust the standard 1M GHC stack. Whether or not result eats memory depends on what x does: if it's a delayed computation then it almost certainly will. This includes consing elements onto a list, and arithmetic operations (counting, summing, etc).