package sqlite3
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=942283a454f4b21f7517f2e8be3d3a30594779c78a6b0478f4b70b8ca7c98cbb
sha512=59ed9dfe340339228513c77f04abaf2a4b42428c0d41f4c9ced17ce24378635d4d0a71329794164ea324365e6021d954ea0ddad76a6992d71c9585f390516ad8
doc/sqlite3/Sqlite3/index.html
Module Sqlite3Source
API for Sqlite 3.* databases
Exceptions
InternalError reason is raised when the bindings detect an unknown/unsupported situation.
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.
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.
DataTypeError msg is raised when you attempt to convert a Data.t structure to an object via an invalid conversion.
SqliteError err_msg is raised after calling Rc.check on a return code that does not indicate success.
Library Information
sqlite_version ()
sqlite_version_info ()
Types
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.
Compiled statement handle. Stores information about compiled statements created by the prepare or prepare_tail functions.
Type of name of a column returned by queries.
Type of row data (with potential NULL-values)
Type of row data (without NULL-values)
Return codes
Column data types
General database operations
val db_open :
?mode:[ `READONLY | `NO_CREATE ] ->
?uri:bool ->
?memory:bool ->
?mutex:[ `NO | `FULL ] ->
?cache:[ `SHARED | `PRIVATE ] ->
?vfs:string ->
string ->
dbdb_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.
let& db = db_open "..." in ...scope that uses db... ensures that the database db is safely closed at the end of the scope, even if there is an exception somewhere in the scope.
enable_load_extension db onoff enable/disable the SQLite3 load extension.
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 contains the contents of the row, the second parameter contains the headers of the columns associated with the row. Exceptions raised within the callback will abort the execution and escape exec.
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.
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.
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.
Prepared Statements
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.
prepare_or_reset db opt_stmt_ref sql if opt_stmt_ref contains Some stmt, then stmt will be reset and returned. Otherwise fresh statement stmt will be prepared, stored as Some stmt in opt_stmt_ref and then returned. This is useful for executing multiple identical commands in a loop, because we can more efficiently reuse the statement from previous iterations.
prepare_tail stmt compile the remaining part of the SQL-statement stmt to bytecode.
NOTE: this really uses the C-function sqlite3_prepare_v2, i.e. avoids the older, deprecated sqlite3_prepare-function.
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.
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.
Data query
Binding data to statements
bind stmt pos data binds the value data to the free variable at position pos of statement stmt. NOTE: the first variable has index 1!
bind_text stmt pos str binds the string str to the parameter at position pos of the statement stmt as text.
bind_bool stmt pos b binds the boolean b to the parameter at position pos of the statement stmt without having to manually convert it to an int64 for use with Data.INT. true is turned into 1, false into 0.
bind_int stmt pos n binds the integer n to the parameter at position pos of the statement stmt without having to manually convert it to an int64 for use with Data.INT.
bind_nativeint stmt pos n binds the integer n to the parameter at position pos of the statement stmt without having to manually convert it to an int64 for use with Data.INT.
bind_int32 stmt pos n binds the 32-bit integer n to the parameter at position pos of the statement stmt without having to manually convert it to an int64 for use with Data.INT.
bind_int64 stmt pos n binds the 64-bit integer n to the parameter at position pos of the statement stmt.
bind_double stmt pos n binds the float n to the parameter at position pos of the statement stmt.
bind_blob stmt pos str binds the string str to the parameter at position pos of the statement stmt as a blob.
bind_values stmt lst binds the Nth element of lst to the Nth parameter of the statement.
bind_name stmt name data binds the value data to the named parameter name of statement stmt.
bind_names stmt lst binds the (name, data) pairs in lst to the parameters of statement stmt.
clear_bindings stmt resets all bindings associated with prepared statement stmt.
Executing statements
step stmt performs one step of the query associated with SQL-statement stmt.
reset stmt resets the statement stmt, e.g. to restart the query, perhaps with different bindings.
iter stmt ~f will call f once per row returned by stepping through stmt. The statement is automatically reset afterwards.
fold stmt ~f ~init folds over the rows returned by stmt with function f and initial value init. The statement is automatically reset afterwards.
Stepwise query convenience functions
User-defined functions
create_funN db name f registers function f under name name with database handle db. The function has arity N.
create_funN db name f registers function f under name name with database handle db. The function has arity 0.
create_fun1 db name f registers function f under name name with database handle db. The function has arity 1.
create_fun2 db name f registers function f under name name with database handle db. The function has arity 2.
create_fun3 db name f registers function f under name name with database handle db. The function has arity 3.
delete_function db name deletes function with name name from database handle db.
Utility functions
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.
sleep ms sleeps at least ms milliseconds.