module Sqlite:API to work with Sqlite databasessig
..end
exception Sqlite_error of string
Sqlite_error
is raised when some sql operation finishes with
error. Error codes can be obtained via db_rc
for functions that take
db
as an argument, and via vm_rc
for functions that take vm
as a
first argument.
When error code is RC_misuse
it usually means that a programming error
made while using the binding. Attempt to use an invalidated db
handle
(i.e. after Sqlite.close
was called on this handle) is an example.
exception Sqlite_done
vm
is finished
and the program tries to fetch non-existing row of query result.exception Sqlite_busy
exception Sqlite_null_value
step_simple
when null value is found in the result row.type
db
type
vm
compile
or compile_simple
functions.
Column names and data types are stored in the vm
handle as soon as
they become known.
vm
handle also stores error code for the last operation if the
function implementing that operation takes virtual machine handle as a
parameter. For example, Sqlite.compile
stores its error code in db
handle because it takes db
handle as the first parameter, but
Sqlite.finalize
stores error code in the vm
handle passed.
type
rc =
| |
RC_ok |
| |
RC_error |
| |
RC_internal |
| |
RC_perm |
| |
RC_abort |
| |
RC_busy |
| |
RC_locked |
| |
RC_nomem |
| |
RC_readonly |
| |
RC_interrupt |
| |
RC_ioerr |
| |
RC_corrupt |
| |
RC_notfound |
| |
RC_full |
| |
RC_cantopen |
| |
RC_protocol |
| |
RC_empty |
| |
RC_schema |
| |
RC_toobig |
| |
RC_constraint |
| |
RC_mismatch |
| |
RC_misuse |
| |
RC_nofls |
| |
RC_auth |
| |
RC_format |
db
handle or vm
handle depending on the function
called. Note: RC_misuse is the common error code when invalid db
or
vm
handle was provided to the function.val db_open : string -> db
Sqlite.db_open filename
opens the database file filename
and
returns a database handle.val db_close : db -> unit
Sqlite.db_close db_handle
Closes a database file and invalidates
the handle. Raises an Sqlite_error
exception if invalalid handle is
provided.val exec : db -> string -> unit
Sqlite.exec db_handle query
executes a query query
. Query
results are ignored.val last_insert_rowid : db -> int
Sqlite.last_insert_rowid db_handle
returns rowid of the last
inserted row.val db_rc : db -> rc
Sqlite.db_rc db_handle
returns the last error code for operations
on db_handle
.vm
handle after
the first attempt to get result row. When there is no query results left
(or there was no rows to fetch at all), attempt to fetch next row leads
to Sqlite_done
exception and immediate finalization of the sqlite
virtual machine used. Column names and types can be obtained even after
the vm
handle is finalized (and thus invalidated) if is was created
using compile
call with third parameter set to true
.val compile : db -> string -> int -> bool -> vm * int * bool
Sqlite.compile db_handle query start keep_col_info
executes a
* query query
.
This function returns a vm
handle and the position of remainder of the
query string, plus the boolean value telling if the end of query string
is reached. keep_col_info
parameter tells if the library should backup
column names and datatypes information in the vm
handle when it is
finalized (in the sense of destroying the virtual machine, i.e.
Sqlite.finalize
call) but not yet garbage collected. Of course, the
information is stored only if it happens to be available at the time of
finalization. start
parameter tells the function to skip that many
characters from the start of query string. This must be useful for the
queries where the query string contains many statements because a vm
handle can be generated only for each statement individuallyval compile_simple : db -> string -> vm
Sqlite.compile_simple db_handle query
executes a query query
.
This function returns a vm
handle; if there was a the remainder of the
query string then it is ignored. Information about column names and
types won't be available after the vm
is finalized.val step : vm -> string -> string array
Sqlite.step vm default_value
executes a query query
and returns
the next row of result in the form of string array. Any NULL values are
replaced with the default_value
. If a query is not expected to return
any result, then this function still should be called at least one for
the query to be executed or use of exec
should be preferred.val step_simple : vm -> string array
Sqlite.step
except that it raises
Sqlite_null_value
exception when result row contains any NULL
values instead of replacing them with some kind of default value.val step_opt : vm -> string option array
Sqlite.step_opt vm
executes a query query
and returns the next
row of result in the form of string option array. NULL values are
represented as None
array elements, and non-NULL values are
represented as Some(value)
array elements.val finalize : vm -> unit
Sqlite.finalize vm
finalizes virtual machine manually thus
invalidating the vm
handle. This function can be used to terminate
query execution in the middle, otherwise the vm is finalized
automatically when error occurs or when all query results are already
fetched and an attempt to read the next (non-existing) result row has
been made.val vm_rc : vm -> rc
Sqlite.vm_rc vm
returns the last error code for operations on vm.val column_names : vm -> string array
Sqlite.column_names vm
returns the column names of query result.
If Sqlite.compile
was called with keep_column_info
parameter set to
true, then column names are available even after vm is finalized.val column_types : vm -> string array
Sqlite.column_types vm
returns the column types of query result.
If Sqlite.compile
was called with keep_column_info
parameter set to
true, then column types are available even after vm is finalized.