Module Sqlite


module Sqlite: sig .. end
API to work with Sqlite databases


Exceptions


exception Sqlite_error of string
Raised when an sqlite operation generates an error. The error code can be obtained with db_rc for functions that take a db as the first argument, and with vm_rc for functions that take a vm as the first argument.

When the error code is RC_misuse, it usually means that a programming error was made. An attempt to use an invalidated db handle (i.e. after Sqlite.close was called on this handle) is an example.

exception Sqlite_done
Raised when an attempt is made to fetch a row from a query result all of whose rows have been fetched.
exception Sqlite_busy
Raised when a query is made to a busy database. The query may be attempted at a later time.
exception Sqlite_null_value
Raised by Sqlite.step_simple when a null value is found in the result row.

Types


type db 
A database handle. A value of this type stores information about an open database and the status code of the last operation which took the database handle as a parameter.
type vm 
A virtual machine handle. A value of this type stores information about a virtual machine created by the compile or compile_simple function.

Column names and data types are stored in a vm handle as soon as they become known.

A vm handle also stores the status code of the last operation which took the virtual machine handle as a parameter. For example, Sqlite.compile stores its status code in the db handle because it takes the db handle as the first parameter, but Sqlite.finalize stores its status 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
Possible status codes from an sqlite operation. Can be obtained from a db handle or a vm handle depending on the function called. Note: RC_misuse is the common error code when an invalid db or vm is passed to a function.

Database operations



General database operations


val db_open : string -> db
Sqlite.db_open f_name opens the database file f_name and returns a database handle.
val db_close : db -> unit
Sqlite.db_close db_handle closes the database file associated with db_handle and invalidates the handle. Raises an Sqlite_error exception if an invalid handle is passed.
val exec : db -> string -> unit
Sqlite.exec db_handle q_string executes the query q_string. The query result is ignored.
val last_insert_rowid : db -> int
Sqlite.last_insert_rowid db_handle returns the rowid of the last inserted row.
val db_rc : db -> rc
Sqlite.db_rc db_handle returns the status code of the last operation on db_handle.

Database operations involving use of the Virtual Machine



The following functions are used to compile a query to the sqlite virtual machine instance. After compilation, result rows can be fetched. Actual execution of the query begins when the first attempt to get a result row is made. Column names and types can be obtained from the vm handle after the first attempt. When there are no result rows left (or there were no rows to fetch at all), an attempt to fetch a row raises an Sqlite_done exception and immediately finalizes the virtual machine involved. Column names and types can be obtained even after the vm handle is finalized (and thus invalidated) if it was created with a compile call with the third parameter set to true.

NOTE: ALL VIRTUAL MACHINE HANDLES MUST BE FINALIZED BEFORE THE DATABASE IS CLOSED!
val compile : db -> string -> int -> bool -> vm * int * bool
Sqlite.compile db_handle q_string skip keep_col_info reads a single query from the string q_string, skipping skip initial characters, and compiles it. It returns a vm handle, the position in q_string of the still-unused part of the string, and a boolean value telling if the end of the string has been reached.

Passing character positions is necessary for strings containing more than one statement, since a vm is associated with a single statement.

If keep_col_info is true, the vm handle will retain information about column names and data types after it is finalized (e.g. with sqlite.finalize), but not yet garbage-collected. Of course, the information is saved only if it is known at the time of finalization.

val compile_simple : db -> string -> vm
Sqlite.compile_simple db_handle q_string compiles a single query, read from the beginning of the string q_string. It returns a vm handle. Any unused remainder of the q_string is ignored. Information about column names and types is not available after the vm is finalized.
val step : vm -> string -> string array
Sqlite.step vm default_value executes vm to return the next row of the result as a string array. Null values are replaced with default_value. Even if the query compiled to vm is not expected to return any rows, the function should be called at least once for the query to be executed. The use of exec is preferred for such queries, however.
val step_simple : vm -> string array
Sqlite.step_simple is the same as Sqlite.step, except that it raises a Sqlite_null_value exception if the result row contains a null value, instead of replacing it with a default value.
val step_opt : vm -> string option array
Sqlite.step_opt vm executes vm and returns the next row of the result as a string option array. Null values are returned as None array elements, and non-null values as Some(value) elements.
val finalize : vm -> unit
Sqlite.finalize vm finalizes vm explicitly, thus invalidating the handle. The vm is finalized automatically when an error occurs or when fetching is attempted on a query all of whose rows have been fetched. Sqlite.finalize may be used to terminate query execution at will, whenever needed.
val vm_rc : vm -> rc
Sqlite.vm_rc vm returns the status code of the last operation on vm.
val column_names : vm -> string array
Sqlite.column_names vm returns the column names of the query result. If Sqlite.compile was called with a true third parameter, the 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 a true third parameter, the column types are available even after vm is finalized.