module Sqlite3:sig
..end
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.type
db
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
prepare
or prepare_tail
functions.
NOTE: DO NOT USE THIS HANDLE WITHIN THREADS OTHER THAN THE ONE THAT
CREATED IT!!!
typeheader =
string
typeheaders =
header array
typerow =
string option array
typerow_not_null =
string array
module Rc:sig
..end
module Data:sig
..end
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, createmutex
: default = nothingcache
: default = nothingvfs
: default = nothingval db_close : db -> bool
db_close db
closes database db
and invalidates the handle.SqliteError
if an invalid database handle is passed.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.false
if the operation fails, true
otherwise.val errcode : db -> Rc.t
errcode db
SqliteError
if an invalid database handle is passed.db
.val errmsg : db -> string
errmsg db
SqliteError
if an invalid database handle is passed.db
.val last_insert_rowid : db -> int64
last_insert_rowid db
SqliteError
if an invalid database handle is passed.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
.SqliteError
if an invalid database handle is passed.cb
: default = no callbackval 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
.SqliteError
if an invalid database handle is passed.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
.SqliteError
if an invalid database handle is passed.SqliteError
if a row contains 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 Sqlite3.exec_not_null_no_headers
.SqliteError
if an invalid database handle is passed.SqliteError
if a row contains NULL.val changes : db -> int
changes db
db
.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.SqliteError
if the statement could not be prepared.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.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
.SqliteError
if the step could not be executed.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.SqliteError
if the statement could not be finalized.val reset : stmt -> Rc.t
reset stmt
resets the statement stmt
, e.g. to restart the query,
perhaps with different bindings.SqliteError
if the statement could not be reset.val sleep : int -> int
sleep ms
sleeps at least ms
milliseconds.val data_count : stmt -> int
data_count stmt
SqliteError
if the statement is invalid.stmt
.val column_count : stmt -> int
column_count stmt
SqliteError
if the statement is invalid.stmt
.val column : stmt -> int -> Data.t
column stmt n
RangeError
if n
is out of range.SqliteError
if the statement is invalid.n
of the
result of the last step of statement stmt
.val column_name : stmt -> int -> header
column_name stmt n
RangeError
if n
is out of range.SqliteError
if the statement is invalid.n
in the
result set of statement stmt
.val column_decltype : stmt -> int -> string option
column_decltype stmt n
RangeError
if n
is out of range.SqliteError
if the statement is invalid.stmt
.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
!RangeError
if n
is out of range.SqliteError
if the statement is invalid.val bind_parameter_count : stmt -> int
bind_parameter_count stmt
SqliteError
if the statement is invalid.stmt
.val bind_parameter_name : stmt -> int -> string option
bind_parameter_name stmt n
RangeError
if n
is out of range.SqliteError
if the statement is invalid.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
Not_found
if name
was not found.SqliteError
if the statement is invalid.name
in statement stmt
.val clear_bindings : stmt -> Rc.t
clear_bindings stmt
resets all bindings associated with prepared
statement stmt
.SqliteError
if the statement is invalid.val row_data : stmt -> Data.t array
row_data stmt
SqliteError
if the statement is invalid.stmt
.val row_names : stmt -> headers
row_names stmt
SqliteError
if the statement is invalid.stmt
.val row_decltypes : stmt -> string option array
row_decltypes stmt
SqliteError
if the statement is invalid.stmt
.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
.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
.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
.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
.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
.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
.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.SqliteError
if an invalid database handle is passed.module Aggregate:sig
..end