module Sqlite: sig .. 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

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.

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.

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.

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.

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.