Module Sqlite


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


Exceptions


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
Raised when step-by-step query execution using a vm is finished and the program tries to fetch non-existing row of query result.
exception Sqlite_busy
Raised when sqlite database is busy. The query can be repeated later.
exception Sqlite_null_value
Raised by step_simple when null value is found in the result row.

Types


type db 
Database handle. Used to store information regarding an open database and error code from the last operation if the function implementing that operation takes database handle as a parameter.
type vm 
Virtual machine handle. Used to store information regarding a virtual machine created by 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
Possible error codes from a failed operation or sqlite misuse. Can be obtained from 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.

Database operations



General database operations


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.

Database operations involving use of Virtual Machine



The following functions are used to compile a query into the sqlite virtual machine instance. After that result rows can be fetched. Actual execution of query starts when the first attempt to get result row has been made. Column names and types can be obtained from 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.

NOTE: ALL VIRTAL MACHINE HANDLES MUST BE FINALIZED BEFORE THE DATABASE IS CLOSED !
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 individually
val 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
This function is equal to 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.