module Sqlite: sig .. end

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.

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.

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.

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.

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.