These classes are derived from <c++-object>. They hold a pointer to the underlying C-structure in their this slot.

<sqlite3:statement> also has a database slot pointing to the database object it belongs to.

Opens the indicated database file and returns a <sqlite3:database> object for it.

The given path is subject to the same special expansion as paths passed to

open-input-file

If proc is given, registers a new collation sequence identified by name for use in the context of database handle db. If no procedure is passed, the collation sequence with the given name is removed.

proc should have the signature (proc (a <string>) (b <string>)) => <exact>. It should return a negative number if a sorts before b, a positive number if b sorts before a and zero if a and b are equal.

As proc will be called in a callback context from within sqlite3:step!, safety measures are installed to avoid throwing any exceptions, invoking continuations or returning invalid values from it. Attempts to do so will result in a 0 return value and warning messages.

If proc is given, registers a new SQL function identified by name for use in the context of database handle db. If step-proc and final-proc are given, the new function becomes an aggregate function. Once registered, functions cannot be deleted.

n is the number of parameters the new SQL function takes or -1 to allow any number of arguments.

proc should have the signature (proc . params) => <top>. It is called with the n parameters given to the SQL function converted into Scheme objects like by sqlite3:column-data. The return value is converted into an SQLite3 data object like by sqlite3:bind!. A return value of (void) corresponds to NULL in SQLite3.

step-proc should have the signature (step-proc (seed <top>) . params) => <top>. It is called with the parameters given to the SQL function for every row being processed. The seed value passed is initially the one given as an argument to sqlite3:define-function; for subsequent calls it is the last value returned by step-proc and after completion of final-proc it will be the initial value again.

final-proc should have the signature (final-proc (seed <top>)) => <top> and transforms the last seed value into the value to be returned from the aggregate function.

As proc, step-proc and final-proc will be called in a callback context from within sqlite3:step!, safety measures are installed to avoid throwing any exceptions, invoking continuations or returning invalid values from them. Attempts to do such things will result in NULL return values and warning messages.

Installs a busy handler that waits at least the specified amount of milliseconds for locks on the given database. If (<= ms 0) though, all busy handlers for the database are uninstalled.

Installs the supplied procedure as the library's busy handler, or removes it if #f. When the database is busy, SQLite will invoke this handler repeatedly until it returns #f. The handler will be called with arguments db (database) and count (number of times invoked for the same operation).

As handler will be called in a callback context from within the library, safety measures are installed to avoid throwing any exceptions or invoking continuations. Attempts to do such things will result in #f return values and warning messages.

Notably, you may not use this procedure in the presence of multiple threads unless you can ensure no other thread will invoke a C to Scheme callback while this handler is executing. In other words, callback entrance and exit must occur in order. Use set-safe-busy-handler! in this case.

Example:
(sqlite3:set-busy-handler! db
 (lambda (db count)
   (cond ((< count 5)
          (sleep 1)
          #t)
         (else #f)))))

Installs the supplied procedure as the application's busy handler, or removes it if #f. When the database returns a busy error code, the egg will invoke this handler repeatedly until it returns #f. The handler will be called with arguments db (database), count (number of times invoked for the same operation), and last (the previous value the handler returned for this operation).

As handler is not called in a callback context, it is legal to invoke captured continuations, and it is safe in the presence of multiple threads. In general, this handler should give up at some point to avoid possible deadlock.

For an example handler, see the code of default-safe-busy-handler.

Returns a handler suitable for use with set-safe-busy-handler!. The behavior is identical to the default SQLite busy handler installed via set-busy-timeout!—it polls in increasing intervals until the timeout in milliseconds is reached—but this version is non-blocking.

Example:
(define open-db
  (let ((handler (sqlite3:default-safe-busy-handler 2000)))
    (lambda (db-name)
      (let ((db (sqlite3:open db-name)))
        (sqlite3:set-safe-busy-handler! db handler)
        db))))

Cancels any running database operation as soon as possible.

This function is always successful and never throws an exception.

Checks whether the database is currently in auto committing mode, i.e. no transaction is currently active.

This function always returns a state and never throws an exception.

Returns the number of rows changed by the last statement (if (not total)) or since the database was opened (if total).

This function always returns a count and never throws an exception.

Returns the row ID of the last row inserted in db.

This function always returns a number and never throws an exception.

Closes the given database.

Compiles the first SQL statement in sql and returns a <sqlite3:statement> and the rest of sql, which was not compiled (or an empty string).

Recompiles the SQL statement used to create stmt, transfers all existing bindings from the old statement handle to the new one and destructively modifies stmt to point to the new statement handle.

If the operation is successful, the old handle is finalized, in case of error, the new handle is finalized and the old one stays untouched.

Usually you should not have to call this routine by hand. It is invoked by sqlite3:step! to automagically repair a stale statement handle after a database schema change.

Can be applied to any statement and returns the number of columns it will return as results.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and returns the name of the column number i (counting from 0) as a string or #f if the column has no name.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and returns the declared type (as given in the CREATE statement) of the column number i (counting from 0) as a string or #f if the column has no declared type.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and returns the number of free parameters that can be bound in the statement.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and returns the index of the bindable parameter called name or #f if no such parameter exists.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and returns the name of the bindable parameter number i (counting from 0) or #f if no such parameter exists or the parameter has no name.

This procedure always succeeds and never throws an exception.

Can be applied to any statement to bind its free parameter number i (counting from 0) to the given value. Scheme types of the value map to SQLite types as follows:

Unless there is internal trouble in SQLite3, this method should always succeeds and never throw an exception. For invalid parameter indices the method just silently does nothing.

Binds the statement's free parameters.

Allows <void> as a parameter.

Single-steps the execution of stmt and returns #t if a result row was produced, #f if no further results are available as the statement has been stepped through. This procedure must be called at least once before any results can be retrieved from the statement.

Can be applied to a statement that has just been stepped (otherwise it returns #f) and returns the SQLite type of the result column number i (counting from 0) as a symbol.

The return value can be one of the symbols null, integer, float, text or blob.

This procedure always succeeds and never throws an exception.

Can be applied to a statement that has just been stepped. Consults sqlite3:column-type to determine the type of the indicated column and to return its data as an appropriate scheme object.

See sqlite3:bind! for the mapping between Scheme and SQLite data types. Columns of type null are returned as <void>. Also keep in mind that CHICKEN's <exact> datatype can only hold a subset of the values an SQLite integer can store. Large integer values may therefore be returned as floating point numbers from the database, but they will still be of class <integer>.

This procedure always succeeds and never throws an exception.

Can be applied to any statement and resets it such that execution using sqlite3:step! will perform all operations of the statement again.

Must be applied to every statement to free its resources and discard it.

sqlite3:close will not be able to close a database that has associated unfinalized statements.

Compiles the SQL sources in sqls into statements in the context of db, applies proc to these statements and returns proc's result. The statements are created and finalized in dynamic-wind entry and exit blocks around the application of proc.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes the statement ignoring possible results from it.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes the specified statement ignoring possible results from it, returning the result of applying sqlite3:changes to the affected database after the execution of the statement instead.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and single-steps the statement once returning the value of the first column in the first result row. Resets the statement again just before returning.

If the given statement does not yield any results, an (exn sqlite3) is thrown with the status-property set to done.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and single-steps the statement once returning all columns in the first result row as a list.

If the given statement does not yield any results, an (exn sqlite3) is thrown with the status-property set to done.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and proc is applied to the current folded value and the column values. The result of the application becomes the new folded value.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and proc is applied to them. The results of this application are discarded.

Allows <void> as a parameter.

(Compiles the given SQL), resets the statement, binds the statement's free parameters and executes it step by step. After each step, the column values of the current result row are retrieved and proc is applied to them. The results of these applications are collected into a list.

Allows <void> as a parameter.

Runs thunk within the scope of a transaction on the database db.

The transaction is committed upon exit from thunk if thunk returns a true value. If thunk returns a false value or throws an exception, the transaction is rolled back.

The type of the transaction can be specified as one of the symbols deferred, immediate or exclusive.

Checks whether sql comprises at least one complete SQL statement.

Enables (or disables) the sharing of the database cache and schema data structures between connections to the same database.

Returns a string identifying the version of SQLite in use.

Returns a Scheme boolean for the usual SQLite column boolean values.

Truth values are Y, y, YES, yes, Yes, and (not (zero? v)).

Anything else is considered false.