package sqlite3

  1. Overview
  2. Docs
SQLite3 bindings for OCaml

Install

Dune Dependency

Authors

Maintainers

Sources

sqlite3-4.4.1.tbz
sha256=db9b84db23c25812dad8b56117d6c9473ee1c43ee79bd434356b688fc03e472f
md5=93763885a3606252aa8004f7662dd161

doc/sqlite3/Sqlite3/index.html

Module Sqlite3Source

API for Sqlite 3.* databases

Exceptions

Sourceexception InternalError of string

InternalError reason is raised when the bindings detect an unknown/unsupported situation.

Sourceexception Error of string

Error reason is raised when some SQL operation is called on a nonexistent handle and the functions does not return a return code, or if there is no error code corresponding to this error. Functions returning return codes communicate errors by returning the specific error code.

Sourceexception RangeError of int * int

RangeError (index, maximum) is raised if some column or bind operation refers to a nonexistent column or binding. The first entry of the returned tuple is the specified index, the second is the limit which was violated.

Types

Sourcetype db

Database handle. Used to store information regarding open databases and the error code from the last operation if the function implementing that operation takes a database handle as a parameter.

NOTE: database handles are closed (see db_close) automatically when they are reclaimed by the GC unless they have already been closed earlier by the user. It is good practice to manually close database handles to free resources as quickly as possible.

Sourcetype stmt

Compiled statement handle. Stores information about compiled statements created by the prepare or prepare_tail functions.

Sourcetype header = string

Type of name of a column returned by queries.

Sourcetype headers = header array

Type of names of columns returned by queries.

Sourcetype row = string option array

Type of row data (with potential NULL-values)

Sourcetype row_not_null = string array

Type of row data (without NULL-values)

Return codes

Sourcemodule Rc : sig ... end

Column data types

Sourcemodule Data : sig ... end

General database operations

Sourceval db_open : ?mode:[ `READONLY | `NO_CREATE ] -> ?uri:bool -> ?memory:bool -> ?mutex:[ `NO | `FULL ] -> ?cache:[ `SHARED | `PRIVATE ] -> ?vfs:string -> string -> db

db_open ?mode ?uri ?memory ?mutex ?cache ?vfs filename opens the database file filename, and returns a database handle.

Special filenames: ":memory:" and "" open an in-memory or temporary database respectively. Behaviour explained here: https://www.sqlite.org/inmemorydb.html

The optional arguments mode, uri, memory and mutex are only meaningful with SQLite versions >= 3.5, cache only for versions >= 3.6.18. For older versions an exception will be raised if any of them is set to a non-default value. The database is opened read-only if `READONLY is passed as mode. The database file will not be created if it is missing and `NO_CREATE is set. The uri parameter enables URI filename interpretation and corresponds to SQLITE_OPEN_URI in the SQLite3 API. The memory parameter opens an in-memory database and corresponds to SQLITE_OPEN_MEMORY in the SQLite3 API. mutex determines how the database is accessed. The mutex parameters `NO and `FULL correspond to SQLITE_OPEN_NOMUTEX and SQLITE_OPEN_FULLMUTEX in the SQLite3 API respectively. The cache parameters `SHARED and `PRIVATE correspond to SQLITE_OPEN_SHAREDCACHE and SQLITE_OPEN_PRIVATECACHE in the SQLite3 API respectively.

  • parameter mode

    default = read-write, create

  • parameter uri

    default = false

  • parameter memory

    default = false

  • parameter mutex

    default = nothing

  • parameter cache

    default = nothing

  • parameter vfs

    default = nothing

Sourceval db_close : db -> bool

db_close db closes database db and invalidates the handle.

  • returns

    false if database was busy (database not closed in this case!), true otherwise.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval enable_load_extension : db -> bool -> bool

enable_load_extension db onoff enable/disable the sqlite3 load extension.

  • returns

    false if the operation fails, true otherwise.

Sourceval errcode : db -> Rc.t

errcode db

  • returns

    the error code of the last operation on database db.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval errmsg : db -> string

errmsg db

  • returns

    the error message of the last operation on database db.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval last_insert_rowid : db -> int64

last_insert_rowid db

  • returns

    the index of the row inserted by the last operation on database db.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval exec : db -> ?cb:(row -> headers -> unit) -> string -> Rc.t

exec db ?cb sql performs SQL-operation sql on database db. If the operation contains query statements, then the callback function cb will be called for each matching row. The first parameter of the callback is the contents of the row, the second paramater are the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape exec.

  • returns

    the return code of the operation.

  • parameter cb

    default = no callback

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval exec_no_headers : db -> cb:(row -> unit) -> string -> Rc.t

exec_no_headers db ?cb sql performs SQL-operation sql on database db. If the operation contains query statements, then the callback function cb will be called for each matching row. The parameter of the callback is the contents of the row. Exceptions raised within the callback will abort the execution and escape exec_no_headers.

  • returns

    the return code of the operation.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval exec_not_null : db -> cb:(row_not_null -> headers -> unit) -> string -> Rc.t

exec_not_null db ~cb sql performs SQL-operation sql on database db. If the operation contains query statements, then the callback function cb will be called for each matching row. The first parameter of the callback is the contents of the row, which must not contain NULL-values, the second paramater are the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape exec_not_null.

  • returns

    the return code of the operation.

  • raises SqliteError

    if an invalid database handle is passed.

  • raises SqliteError

    if a row contains NULL.

Sourceval exec_not_null_no_headers : db -> cb:(row_not_null -> unit) -> string -> Rc.t

exec_not_null_no_headers db ~cb sql performs SQL-operation sql on database db. If the operation contains query statements, then the callback function cb will be called for each matching row. The parameter of the callback is the contents of the row, which must not contain NULL-values. Exceptions raised within the callback will abort the execution and escape exec_not_null_no_headers.

  • returns

    the return code of the operation.

  • raises SqliteError

    if an invalid database handle is passed.

  • raises SqliteError

    if a row contains NULL.

Sourceval changes : db -> int

changes db

  • returns

    the number of rows that were changed or inserted or deleted by the most recently completed SQL statement on database db.

Fine grained query operations

Sourceval prepare : db -> string -> stmt

prepare db sql compile SQL-statement sql for database db into bytecode. The statement may be only partially compiled. In this case prepare_tail can be called on the returned statement to compile the remaining part of the SQL-statement.

NOTE: this really uses the C-function sqlite3_prepare_v2, i.e. avoids the older, deprecated sqlite3_prepare-function.

  • raises SqliteError

    if an invalid database handle is passed.

  • raises SqliteError

    if the statement could not be prepared.

Sourceval prepare_tail : stmt -> stmt option

prepare_tail stmt compile the remaining part of the SQL-statement stmt to bytecode.

  • returns

    None if there was no remaining part, or Some remaining_part otherwise.

NOTE: this really uses the C-function sqlite3_prepare_v2, i.e. avoids the older, deprecated sqlite3_prepare-function.

  • raises SqliteError

    if the statement could not be prepared.

Sourceval recompile : stmt -> unit

recompile stmt recompiles the SQL-statement associated with stmt to bytecode. The statement may be only partially compiled. In this case prepare_tail can be called on the statement to compile the remaining part of the SQL-statement. Call this function if the statement expires due to some schema change.

  • raises SqliteError

    if the statement could not be recompiled.

Sourceval step : stmt -> Rc.t

step stmt performs one step of the query associated with SQL-statement stmt.

  • returns

    the return code of this operation.

  • raises SqliteError

    if the step could not be executed.

Sourceval finalize : stmt -> Rc.t

finalize stmt finalizes the statement stmt. After finalization, the only valid usage of the statement is to use it in prepare_tail, or to recompile it.

  • returns

    the return code of this operation.

  • raises SqliteError

    if the statement could not be finalized.

Sourceval reset : stmt -> Rc.t

reset stmt resets the statement stmt, e.g. to restart the query, perhaps with different bindings.

  • returns

    the return code of this operation.

  • raises SqliteError

    if the statement could not be reset.

Sourceval sleep : int -> int

sleep ms sleeps at least ms milliseconds.

  • returns

    the number of milliseconds of sleep actually requested from the operating system.

Data query

Sourceval data_count : stmt -> int

data_count stmt

  • returns

    the number of columns in the result of the last step of statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval column_count : stmt -> int

column_count stmt

  • returns

    the number of columns that would be returned by executing statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval column_blob : stmt -> int -> string option

column_blob stmt n

  • returns

    Some bytes in column n of the result of the last step of statement stmt, or None if NULL.

  • raises SqliteError

    if the statement is invalid.

Sourceval column : stmt -> int -> Data.t

column stmt n

  • returns

    the data in column n of the result of the last step of statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval column_name : stmt -> int -> header

column_name stmt n

  • returns

    the header of column n in the result set of statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval column_decltype : stmt -> int -> string option

column_decltype stmt n

  • returns

    the declared type of the specified column in the result set of statement stmt.

  • raises SqliteError

    if the statement is invalid.

Binding data to the query

Sourceval bind : stmt -> int -> Data.t -> Rc.t

bind stmt n data binds the value data to the free variable at position n of statement stmt. NOTE: the first variable has index 1!

  • returns

    the return code of this operation.

  • raises SqliteError

    if the statement is invalid.

Sourceval bind_parameter_count : stmt -> int

bind_parameter_count stmt

  • returns

    the number of free variables in statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval bind_parameter_name : stmt -> int -> string option

bind_parameter_name stmt n

  • returns

    Some parameter_name of the free variable at position n of statement stmt, or None if it is ordinary ("?").

  • raises SqliteError

    if the statement is invalid.

Sourceval bind_parameter_index : stmt -> string -> int

bind_parameter_index stmt name

  • returns

    the position of the free variable with name name in statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval clear_bindings : stmt -> Rc.t

clear_bindings stmt resets all bindings associated with prepared statement stmt.

  • returns

    the return code of this operation.

  • raises SqliteError

    if the statement is invalid.

Stepwise query convenience functions

Sourceval row_blobs : stmt -> row

row_blobs stmt

  • returns

    the row returned by the last query step performed with statement stmt (array of optional blobs).

  • raises SqliteError

    if the statement is invalid.

Sourceval row_data : stmt -> Data.t array

row_data stmt

  • returns

    all data values in the row returned by the last query step performed with statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval row_names : stmt -> headers

row_names stmt

  • returns

    all column headers of the row returned by the last query step performed with statement stmt.

  • raises SqliteError

    if the statement is invalid.

Sourceval row_decltypes : stmt -> string option array

row_decltypes stmt

  • returns

    all column type declarations of the row returned by the last query step performed with statement stmt.

  • raises SqliteError

    if the statement is invalid.

User-defined functions

Sourceval create_funN : db -> string -> (Data.t array -> Data.t) -> unit

create_funN db name f registers function f under name name with database handle db. The function has arity N.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval create_fun0 : db -> string -> (unit -> Data.t) -> unit

create_funN db name f registers function f under name name with database handle db. The function has arity 0.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval create_fun1 : db -> string -> (Data.t -> Data.t) -> unit

create_fun1 db name f registers function f under name name with database handle db. The function has arity 1.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval create_fun2 : db -> string -> (Data.t -> Data.t -> Data.t) -> unit

create_fun2 db name f registers function f under name name with database handle db. The function has arity 2.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval create_fun3 : db -> string -> (Data.t -> Data.t -> Data.t -> Data.t) -> unit

create_fun3 db name f registers function f under name name with database handle db. The function has arity 3.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval delete_function : db -> string -> unit

delete_function db name deletes function with name name from database handle db.

  • raises SqliteError

    if an invalid database handle is passed.

Sourceval busy_timeout : db -> int -> unit

busy_timeout db ms sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least ms milliseconds of sleeping have accumulated.

  • raises SqliteError

    if an invalid database handle is passed.

Sourcemodule Aggregate : sig ... end
Sourcemodule Backup : sig ... end
OCaml

Innovation. Community. Security.