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 : string -> db
db_open filename opens the database file filename, and returns a database handle.
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 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 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 Returns the return code of the operation.

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

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 expired : stmt -> bool
expired stmt
Raises SqliteError if the statement is invalid.
Returns true if the statement stmt has expired. In this case it may need to be recompiled.

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 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 Returns the header of column n in the result set of statement stmt.
val column_decltype : stmt -> int -> string
column_decltype stmt n
Raises 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 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 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 Returns the position of the free variable with name name in statement stmt.
val transfer_bindings : stmt -> stmt -> Rc.t
transfer_bindings stmt1 stmt2 transfer the bindings of statement stmt1 to stmt2.
Raises SqliteError if any of the two statements 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 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_funN 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_funN 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_funN 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.