sqlexpr 0.8.0 · OCaml Package

type 'a result

Concurrency monad value.

type ('a, 'b) statement = {

sql_statement : string;
stmt_id : string option;
directive : ((Sqlite3.Data.t list * int * string * string option) -> 'b) -> (Sqlite3.Data.t list * int * string * string option) -> 'a;

}

Type of SQL statements (no output parameters).

type ('a, 'b, 'c) expression = {

statement : ('a, 'c) statement;
get_data : int * (Sqlite3.Data.t array -> 'b);

}

Type of SQL expressions (output parameters).

type db

Database type

exception Error of string * exn

Exception identical to the toplevel Error, provided for convenience. Note that Sqlexpr_sqlite.Error _ matches this exception.

exception Sqlite_error of string * Sqlite3.Rc.t

Exception identical to the toplevel Sqlite_error, provided for convenience. Note that Sqlexpr_sqlite.Sqlite_error _ matches this exception.

val set_retry_on_busy : bool -> unit

Specify whether to retry operations by default when SQLite3 returns * BUSY. (As of 0.6.0, the modules supplied with sqlexpr use false as their * default value; will likely be changed to true in a subsequent release.)

val get_retry_on_busy : unit -> bool

Returns whether operations are retried by default when SQLite3 returns * BUSY. (As of 0.6.0, the modules supplied with sqlexpr use false as their * default value; will likely be changed to true in a subsequent release.)

val open_db : ?init:(Sqlite3.db -> unit) -> string -> db

Open the DB whose filename is given. ":memory:" refers to an in-mem DB. * *

parameter init
function to be applied to Sqlite3.db handle(s) before * they are used (can be used to register functions or initialize schema in * in-mem tables.

val close_db : db -> unit

Close the DB and finalize all the associated prepared statements.

val borrow_worker : db -> (db -> 'a result) -> 'a result

borrow_worker db f evaluates f db' where db' borrows a 'worker' * from db and db' is only valid inside f. All the operations on * db' will use the same worker. Use this e.g. if you have an in-mem * database and a number of operations that must go against the same * instance (since data is not shared across different :memory: * databases). db' will not spawn new workers and will be closed and * invalidated automatically.

val steal_worker : db -> (db -> 'a result) -> 'a result

steal_worker db f is similar to borrow_worker db f, but ensures * that f is given exclusive access to the worker while it is being * evaluated.

val execute : db -> ('a, unit result) statement -> 'a

Execute a SQL statement.

val insert : db -> ('a, int64 result) statement -> 'a

Execute an INSERT SQL statement and return the last inserted row id. Example: insert db sqlc"INSERT INTO users(name, pass) VALUES(%s, %s)" name pass

val select : db -> ?batch:int -> ('c, 'a, 'a list result) expression -> 'c

"Select" a SELECT SQL expression and return a list of tuples; e.g. select db sqlc"SELECT \@s\{name\}, \@s\{pass\} FROM users" select db sqlc"SELECT \@s\{pass\} FROM users WHERE id = %L" user_id

If batch is not 1, some worker pool implementations might choose to read multiple rows at a time to make the operation faster.

val select_f : 
  db ->
  ?batch:int ->
  ('a -> 'b result) ->
  ('c, 'a, 'b list result) expression ->
  'c

select_f db f expr ... is similar to select db expr ... but maps the results using the provided f function.

If batch is not 1, some worker pool implementations might choose to read multiple rows at a time to make the operation faster.

val select_one : db -> ('c, 'a, 'a result) expression -> 'c

select_one db expr ... takes the first result from select db expr ....

raises Not_found
if no row is found.

val select_one_maybe : db -> ('c, 'a, 'a option result) expression -> 'c

select_one_maybe db expr ... takes the first result from select db expr ....

returns
None if no row is found.

val select_one_f : 
  db ->
  ('a -> 'b result) ->
  ('c, 'a, 'b result) expression ->
  'c

select_one_f db f expr ... is returns the first result from select_f db f expr ....

raises Not_found
if no row is found.

val select_one_f_maybe : 
  db ->
  ('a -> 'b result) ->
  ('c, 'a, 'b option result) expression ->
  'c

select_one_f_maybe db expr ... takes the first result from select_f db f expr ....

returns
None if no row is found.

val transaction : 
  db ->
  ?kind:[ `DEFERRED | `IMMEDIATE | `EXCLUSIVE ] ->
  (db -> 'a result) ->
  'a result

Run the provided function in a DB transaction. A rollback is performed if an exception is raised inside the transaction.

If the BEGIN or COMMIT SQL statements from the outermost transaction fail with SQLITE_BUSY, they will be retried until they can be executed. A SQLITE_BUSY (or any other) error code in any other operation inside a transaction will result in an Error (_, Sqlite_error (code, _)) exception being thrown, and a rollback performed. Refer to set_retry_on_busy.

One consequence of this is that concurrency control is very simple if you use `EXCLUSIVE transactions: the code can be written straightforwardly as S.transaction db (fun db -> ...), and their execution will be serialized (across both threads and processes). Note that, for `IMMEDIATE and `DEFERRED transactions, you will have to retry manually if an Error (_, Sqlite_error (Sqlite3.Rc.Busy, _)) is raised.

All SQL operations performed within a transaction will use the same worker. This worker is used exclusively by only one thread per instantiated module (see steal_worker). That is, given

module S1 = Sqlexpr_sqlite.Make(Sqlexpr_concurrency.Id)
module S2 = Sqlexpr_sqlite.Make(Sqlexpr_concurrency.Lwt)
let db = S1.open_db somefile

there is no exclusion between functions from S1 and those from S2.

parameter kind
transaction kind, only meaningful for outermost transaction (default `DEFERRED)

val fold : 
  db ->
  ?batch:int ->
  ('a -> 'b -> 'a result) ->
  'a ->
  ('c, 'b, 'a result) expression ->
  'c

fold db f a expr ... is * f (... (f (f a r1) r2) ...) rN * where rN is the n-th row returned for the SELECT expression expr. * If batch is not 1, some worker pool implementations might choose to * read multiple rows at a time to make this operation faster. *

val iter : 
  db ->
  ?batch:int ->
  ('a -> unit result) ->
  ('b, 'a, unit result) expression ->
  'b

Iterate through the rows returned for the supplied expression. * If batch is not 1, some worker pool implementations might choose to * read multiple rows at a time to make this operation faster. *

module Directives : sig ... end

Module used by the code generated for SQL literals.

module Conversion : sig ... end

Module used by the code generated for SQL literals.

package sqlexpr