Library
Module
Module type
Parameter
Class
Class type
API for Sqlite 3.* databases
InternalError reason
is raised when the bindings detect an unknown/unsupported situation.
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.
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.
DataTypeError msg
is raised when you attempt to convert a Data.t
structure to an object via an invalid conversion.
SqliteError err_msg
is raised after calling Rc.check
on a return code that does not indicate success.
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: database handles are closed (see 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.
Compiled statement handle. Stores information about compiled statements created by the prepare
or prepare_tail
functions.
type headers = header array
Type of names of columns returned by queries.
module Rc : sig ... end
module Data : sig ... end
val db_open :
?mode:[ `READONLY | `NO_CREATE ] ->
?uri:bool ->
?memory:bool ->
?mutex:[ `NO | `FULL ] ->
?cache:[ `SHARED | `PRIVATE ] ->
?vfs:string ->
string ->
db
db_open ?mode ?uri ?memory ?mutex ?cache ?vfs filename
opens the database file filename
, and returns a database handle.
Special filenames: ":memory:" and "" open an in-memory or temporary database respectively. Behaviour explained here: https://www.sqlite.org/inmemorydb.html
The optional arguments mode
, uri
, memory
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. The uri
parameter enables URI filename interpretation and corresponds to SQLITE_OPEN_URI
in the SQLite3 API. The memory
parameter opens an in-memory database and corresponds to SQLITE_OPEN_MEMORY
in the SQLite3 API. 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.
val db_close : db -> bool
db_close db
closes database db
and invalidates the handle.
let& db = db_open "..." in ...scope that uses db...
ensures that the database db
is safely closed at the end of the scope, even if there is an exception somewhere in the scope.
val enable_load_extension : db -> bool -> bool
enable_load_extension db onoff
enable/disable the SQLite3 load extension.
val errmsg : db -> string
errmsg db
val extended_errcode_int : db -> int
extended_errcode_int db
val last_insert_rowid : db -> int64
last_insert_rowid db
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 contains the contents of the row, the second parameter contains the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape exec
.
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 exec_no_headers
.
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 exec_not_null
.
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 exec_not_null_no_headers
.
val changes : db -> int
changes db
prepare db sql
compile SQL-statement sql
for database db
into bytecode. The statement may be only partially compiled. In this case 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.
prepare_or_reset db opt_stmt_ref sql
if opt_stmt_ref
contains Some stmt
, then stmt
will be reset and returned. Otherwise fresh statement stmt
will be prepared, stored as Some stmt
in opt_stmt_ref
and then returned. This is useful for executing multiple identical commands in a loop, because we can more efficiently reuse the statement from previous iterations.
prepare_tail stmt
compile the remaining part of the SQL-statement stmt
to bytecode.
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 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.
finalize stmt
finalizes the statement stmt
. After finalization, the only valid usage of the statement is to use it in prepare_tail
, or to recompile
it.
val data_count : stmt -> int
data_count stmt
val column_count : stmt -> int
column_count stmt
val column_bool : stmt -> int -> bool
column_bool stmt n
val column_text : stmt -> int -> string
column_text stmt n
val column_int : stmt -> int -> int
column_int stmt n
val column_nativeint : stmt -> int -> nativeint
column_nativeint stmt n
val column_int32 : stmt -> int -> int32
column_int32 stmt n
val column_int64 : stmt -> int -> int64
column_int64 stmt n
val column_double : stmt -> int -> float
column_double stmt n
val column_blob : stmt -> int -> string
column_blob stmt n
val column_decltype : stmt -> int -> string option
column_decltype stmt n
bind stmt pos data
binds the value data
to the free variable at position pos
of statement stmt
. NOTE: the first variable has index 1
!
bind_text stmt pos str
binds the string str
to the parameter at position pos
of the statement stmt
as text.
bind_bool stmt pos b
binds the boolean b
to the parameter at position pos
of the statement stmt
without having to manually convert it to an int64
for use with Data.INT
. true
is turned into 1, false
into 0.
bind_int stmt pos n
binds the integer n
to the parameter at position pos
of the statement stmt
without having to manually convert it to an int64
for use with Data.INT
.
bind_nativeint stmt pos n
binds the integer n
to the parameter at position pos
of the statement stmt
without having to manually convert it to an int64
for use with Data.INT
.
bind_int32 stmt pos n
binds the 32-bit integer n
to the parameter at position pos
of the statement stmt
without having to manually convert it to an int64
for use with Data.INT
.
bind_int64 stmt pos n
binds the 64-bit integer n
to the parameter at position pos
of the statement stmt
.
bind_double stmt pos n
binds the float n
to the parameter at position pos
of the statement stmt
.
bind_blob stmt pos str
binds the string str
to the parameter at position pos
of the statement stmt
as a blob.
bind_values stmt lst
binds the Nth element of lst
to the Nth parameter of the statement.
bind_name stmt name data
binds the value data
to the named parameter name
of statement stmt
.
bind_names stmt lst
binds the (name, data)
pairs in lst
to the parameters of statement stmt
.
val bind_parameter_count : stmt -> int
bind_parameter_count stmt
val bind_parameter_name : stmt -> int -> string option
bind_parameter_name stmt pos
val bind_parameter_index : stmt -> string -> int
bind_parameter_index stmt name
clear_bindings stmt
resets all bindings associated with prepared statement stmt
.
reset stmt
resets the statement stmt
, e.g. to restart the query, perhaps with different bindings.
iter stmt ~f
will call f
once per row returned by stepping through stmt
. The statement is automatically reset afterwards.
fold stmt ~f ~init
folds over the rows returned by stmt
with function f
and initial value init
. The statement is automatically reset afterwards.
val row_blobs : stmt -> string array
row_blobs stmt
val row_decltypes : stmt -> string option array
row_decltypes stmt
create_funN db name f
registers function f
under name name
with database handle db
. The function has arity N
.
create_funN db name f
registers function f
under name name
with database handle db
. The function has arity 0
.
create_fun1 db name f
registers function f
under name name
with database handle db
. The function has arity 1
.
create_fun2 db name f
registers function f
under name name
with database handle db
. The function has arity 2
.
create_fun3 db name f
registers function f
under name name
with database handle db
. The function has arity 3
.
val delete_function : db -> string -> unit
delete_function db name
deletes function with name name
from database handle db
.
module Aggregate : sig ... end
Create user-defined aggregate and window functions.
module Backup : sig ... end
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.