Sqlite3

# Module Sqlite3

    module Sqlite3: sig .. end

API for Sqlite 3.* databases

## Exceptions

    exception InternalError of string

`InternalError reason` is raised when the bindings detect an unknown/unsupported situation.

    exception Error of string

`Error reason` is raised when some SQL operation is called on a nonexistent handle and the functions does not return a return code, or if there is no error code corresponding to this error. Functions returning return codes communicate errors by returning the specific error code.

    exception RangeError of int * int

`RangeError (index, maximum)` is raised if some column or bind operation refers to a nonexistent column or binding. The first entry of the returned tuple is the specified index, the second is the limit which was violated.

## Types

    type db

Database handle. Used to store information regarding open databases and the error code from the last operation if the function implementing that operation takes a database handle as a parameter.

NOTE: DO NOT USE THIS HANDLE WITHIN THREADS OTHER THAN THE ONE THAT CREATED IT!!!

NOTE: database handles are closed (see `Sqlite3.db_close`) automatically when they are reclaimed by the GC unless they have already been closed earlier by the user. It is good practice to manually close database handles to free resources as quickly as possible.

    type stmt

Compiled statement handle. Stores information about compiled statements created by the `prepare` or `prepare_tail` functions.

NOTE: DO NOT USE THIS HANDLE WITHIN THREADS OTHER THAN THE ONE THAT CREATED IT!!!

    type header = string

Type of name of a column returned by queries.

    type headers = header array

Type of names of columns returned by queries.

    type row = string option array

Type of row data (with potential NULL-values)

    type row_not_null = string array

Type of row data (without NULL-values)

## Return codes

    module Rc: sig .. end

## Column data types

    module Data: sig .. end

## General database operations

    val db_open : ?mode:[ `NO_CREATE | `READONLY ] ->
           ?mutex:[ `FULL | `NO ] ->
           ?cache:[ `PRIVATE | `SHARED ] -> ?vfs:string -> string -> db

`db_open ?mode ?mutex ?cache ?vfs filename` opens the database file `filename`, and returns a database handle.

The optional arguments `mode` and `mutex` are only meaningful with SQlite versions >= 3.5, `cache` only for versions >= 3.6.18. For older versions an exception will be raised if any of them is set to a non-default value. The database is opened read-only if ``READONLY` is passed as mode. The database file will not be created if it is missing and ``NO_CREATE` is set. `mutex` determines how the database is accessed. The mutex parameters ``NO` and ``FULL` correspond to `SQLITE_OPEN_NOMUTEX` and `SQLITE_OPEN_FULLMUTEX` in the SQLite3 API respectively. The cache parameters ``SHARED` and ``PRIVATE` correspond to `SQLITE_OPEN_SHAREDCACHE` and `SQLITE_OPEN_PRIVATECACHE` in the SQLite3 API respectively.

`mode` : default = read-write, create
`mutex` : default = nothing
`cache` : default = nothing
`vfs` : default = nothing

    val db_close : db -> bool

`db_close db` closes database `db` and invalidates the handle.
Raises `SqliteError` if an invalid database handle is passed.
Returns `false` if database was busy (database not closed in this case!), `true` otherwise.

    val enable_load_extension : db -> bool -> bool

`enable_load_extension db onoff` enable/disable the sqlite3 load extension.
Returns `false` if the operation fails, `true` otherwise.

    val errcode : db -> Rc.t

`errcode db`
Raises `SqliteError` if an invalid database handle is passed.
Returns the error code of the last operation on database `db`.

    val errmsg : db -> string

`errmsg db`
Raises `SqliteError` if an invalid database handle is passed.
Returns the error message of the last operation on database `db`.

    val last_insert_rowid : db -> int64

`last_insert_rowid db`
Raises `SqliteError` if an invalid database handle is passed.
Returns the index of the row inserted by the last operation on database `db`.

    val exec : db ->
           ?cb:(row -> headers -> unit) -> string -> Rc.t

`exec db ?cb sql` performs SQL-operation `sql` on database `db`. If the operation contains query statements, then the callback function `cb` will be called for each matching row. The first parameter of the callback is the contents of the row, the second paramater are the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape `Sqlite3.exec`.
Raises `SqliteError` if an invalid database handle is passed.
Returns the return code of the operation.
`cb` : default = no callback

    val exec_no_headers : db -> cb:(row -> unit) -> string -> Rc.t

`exec_no_headers db ?cb sql` performs SQL-operation `sql` on database `db`. If the operation contains query statements, then the callback function `cb` will be called for each matching row. The parameter of the callback is the contents of the row. Exceptions raised within the callback will abort the execution and escape `Sqlite3.exec_no_headers`.
Raises `SqliteError` if an invalid database handle is passed.
Returns the return code of the operation.

    val exec_not_null : db ->
           cb:(row_not_null -> headers -> unit) ->
           string -> Rc.t

`exec_not_null db ~cb sql` performs SQL-operation `sql` on database `db`. If the operation contains query statements, then the callback function `cb` will be called for each matching row. The first parameter of the callback is the contents of the row, which must not contain NULL-values, the second paramater are the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape `Sqlite3.exec_not_null`.
Raises

- `SqliteError` if an invalid database handle is passed.
- `SqliteError` if a row contains NULL.

Returns the return code of the operation.

    val exec_not_null_no_headers : db -> cb:(row_not_null -> unit) -> string -> Rc.t

`exec_not_null_no_headers db ~cb sql` performs SQL-operation `sql` on database `db`. If the operation contains query statements, then the callback function `cb` will be called for each matching row. The parameter of the callback is the contents of the row, which must not contain NULL-values. Exceptions raised within the callback will abort the execution and escape `Sqlite3.exec_not_null_no_headers`.
Raises

- `SqliteError` if an invalid database handle is passed.
- `SqliteError` if a row contains NULL.

Returns the return code of the operation.

    val changes : db -> int

`changes db`
Returns the number of rows that were changed or inserted or deleted by the most recently completed SQL statement on database `db`.

## Fine grained query operations

    val prepare : db -> string -> stmt

`prepare db sql` compile SQL-statement `sql` for database `db` into bytecode. The statement may be only partially compiled. In this case `Sqlite3.prepare_tail` can be called on the returned statement to compile the remaining part of the SQL-statement.

NOTE: this really uses the C-function `sqlite3_prepare_v2`, i.e. avoids the older, deprecated `sqlite3_prepare`-function.
Raises

- `SqliteError` if an invalid database handle is passed.
- `SqliteError` if the statement could not be prepared.

    val prepare_tail : stmt -> stmt option

`prepare_tail stmt` compile the remaining part of the SQL-statement `stmt` to bytecode.
Raises `SqliteError` if the statement could not be prepared.
Returns `None` if there was no remaining part, or `Some remaining_part` otherwise.

NOTE: this really uses the C-function `sqlite3_prepare_v2`, i.e. avoids the older, deprecated `sqlite3_prepare`-function.

    val recompile : stmt -> unit

`recompile stmt` recompiles the SQL-statement associated with `stmt` to bytecode. The statement may be only partially compiled. In this case `Sqlite3.prepare_tail` can be called on the statement to compile the remaining part of the SQL-statement. Call this function if the statement expires due to some schema change.
Raises `SqliteError` if the statement could not be recompiled.

    val step : stmt -> Rc.t

`step stmt` performs one step of the query associated with SQL-statement `stmt`.
Raises `SqliteError` if the step could not be executed.
Returns the return code of this operation.

    val finalize : stmt -> Rc.t

`finalize stmt` finalizes the statement `stmt`. After finalization, the only valid usage of the statement is to use it in `Sqlite3.prepare_tail`, or to `Sqlite3.recompile` it.
Raises `SqliteError` if the statement could not be finalized.
Returns the return code of this operation.

    val reset : stmt -> Rc.t

`reset stmt` resets the statement `stmt`, e.g. to restart the query, perhaps with different bindings.
Raises `SqliteError` if the statement could not be reset.
Returns the return code of this operation.

    val sleep : int -> int

`sleep ms` sleeps at least `ms` milliseconds.
Returns the number of milliseconds of sleep actually requested from the operating system.

## Data query

    val data_count : stmt -> int

`data_count stmt`
Raises `SqliteError` if the statement is invalid.
Returns the number of columns in the result of the last step of statement `stmt`.

    val column_count : stmt -> int

`column_count stmt`
Raises `SqliteError` if the statement is invalid.
Returns the number of columns that would be returned by executing statement `stmt`.

    val column : stmt -> int -> Data.t

`column stmt n`
Raises

- `RangeError` if `n` is out of range.
- `SqliteError` if the statement is invalid.

Returns the data in column `n` of the result of the last step of statement `stmt`.

    val column_name : stmt -> int -> header

`column_name stmt n`
Raises

- `RangeError` if `n` is out of range.
- `SqliteError` if the statement is invalid.

Returns the header of column `n` in the result set of statement `stmt`.

    val column_decltype : stmt -> int -> string option

`column_decltype stmt n`
Raises

- `RangeError` if `n` is out of range.
- `SqliteError` if the statement is invalid.

Returns the declared type of the specified column in the result set of statement `stmt`.

## Binding data to the query

    val bind : stmt -> int -> Data.t -> Rc.t

`bind stmt n data` binds the value `data` to the free variable at position `n` of statement `stmt`. NOTE: the first variable has index `1`!
Raises

- `RangeError` if `n` is out of range.
- `SqliteError` if the statement is invalid.

Returns the return code of this operation.

    val bind_parameter_count : stmt -> int

`bind_parameter_count stmt`
Raises `SqliteError` if the statement is invalid.
Returns the number of free variables in statement `stmt`.

    val bind_parameter_name : stmt -> int -> string option

`bind_parameter_name stmt n`
Raises

- `RangeError` if `n` is out of range.
- `SqliteError` if the statement is invalid.

Returns `Some parameter_name` of the free variable at position `n` of statement `stmt`, or `None` if it is ordinary ("?").

    val bind_parameter_index : stmt -> string -> int

`bind_parameter_index stmt name`
Raises

- `Not_found` if `name` was not found.
- `SqliteError` if the statement is invalid.

Returns the position of the free variable with name `name` in statement `stmt`.

    val clear_bindings : stmt -> Rc.t

`clear_bindings stmt` resets all bindings associated with prepared statement `stmt`.
Raises `SqliteError` if the statement is invalid.
Returns the return code of this operation.

## Stepwise query convenience functions

    val row_data : stmt -> Data.t array

`row_data stmt`
Raises `SqliteError` if the statement is invalid.
Returns all data values in the row returned by the last query step performed with statement `stmt`.

    val row_names : stmt -> headers

`row_names stmt`
Raises `SqliteError` if the statement is invalid.
Returns all column headers of the row returned by the last query step performed with statement `stmt`.

    val row_decltypes : stmt -> string option array

`row_decltypes stmt`
Raises `SqliteError` if the statement is invalid.
Returns all column type declarations of the row returned by the last query step performed with statement `stmt`.

## User-defined functions

    val create_funN : db -> string -> (Data.t array -> Data.t) -> unit

`create_funN db name f` registers function `f` under name `name` with database handle `db`. The function has arity `N`.
Raises `SqliteError` if an invalid database handle is passed.

    val create_fun0 : db -> string -> (unit -> Data.t) -> unit

`create_funN db name f` registers function `f` under name `name` with database handle `db`. The function has arity `0`.
Raises `SqliteError` if an invalid database handle is passed.

    val create_fun1 : db -> string -> (Data.t -> Data.t) -> unit

`create_fun1 db name f` registers function `f` under name `name` with database handle `db`. The function has arity `1`.
Raises `SqliteError` if an invalid database handle is passed.

    val create_fun2 : db ->
           string -> (Data.t -> Data.t -> Data.t) -> unit

`create_fun2 db name f` registers function `f` under name `name` with database handle `db`. The function has arity `2`.
Raises `SqliteError` if an invalid database handle is passed.

    val create_fun3 : db ->
           string ->
           (Data.t -> Data.t -> Data.t -> Data.t) ->
           unit

`create_fun3 db name f` registers function `f` under name `name` with database handle `db`. The function has arity `3`.
Raises `SqliteError` if an invalid database handle is passed.

    val delete_function : db -> string -> unit

`delete_function db name` deletes function with name `name` from database handle `db`.
Raises `SqliteError` if an invalid database handle is passed.

    val busy_timeout : db -> int -> unit

`busy_timeout db ms` sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least `ms` milliseconds of sleeping have accumulated.
Raises `SqliteError` if an invalid database handle is passed.

    module Aggregate: sig .. end