Module Octez_sqlite.Sqlite

type t

A handler to the database.

type conn

A direct connection to the database, allowing to interact with it.

type perm =
  1. | Read_only of {
    1. pool_size : int;
    }
  2. | Read_write

Permission mode for database access.

Note that SQLite uses file-level locking for write operations. When using Read_write mode, write operations will acquire an exclusive lock on the database file, preventing other processes from writing to it simultaneously. In this case the pool size is always 1. In Read_only mode, multiple processes can read concurrently.

Initialization and backup

val init : path:string -> perm:perm -> ?max_conn_reuse_count:int -> (conn -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t) -> t Tezos_error_monad.Error_monad.tzresult Lwt.t

init ~path ~perm migratrion returns a handler to the database located at path and executes the given migration code.

If sqlite_journal_mode is `Force mode, then the journal mode of the SQLite database is updated if necessary to match the requested configuration. With `Identity, the journal mode is left untouched.

If perm is `Read_only, then SQL requests requiring write access will fail. With `Read_write, they will succeed as expected.

pool_size defaults to 8 and is the size of the connection pool.

If ?max_conn_reuse_count:n is provided, every connection in the pool will be reused at most n times, after which it will be disposed of.

val close : t -> unit Lwt.t
val vacuum : conn:conn -> output_db_file:string -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t

Rebuild the database in output_db_file using the VACUUM sqlite command. This function is useful to backup the database.

val vacuum_self : conn:conn -> unit Tezos_error_monad.Error_monad.tzresult Lwt.t

Vacuums the database itself after removing lot of data VACUUM sqlite command.

Database connections

use db k executes k with a fresh connection to db.

with_transaction conn k wraps the accesses to the database from conn made in the continuation k within a SQL transaction. If k fails, the transaction is rollbacked. Otherwise, the transaction is committed.

val assert_in_transaction : conn -> unit

assert_in_transaction conn raises an exception if a transaction has not been started with conn.

  • raises Assert_failure

Database low level queries

module Request : sig ... end

Module for creating SQL requests with metadata for tracing and debugging. This is a wrapper around Caqti's request system with additional metadata.

module Db : sig ... end

Caqti convenience functions wrapped in the Tezos error monad. See Caqti_connection_sig.Convenience.

val with_connection : conn -> (Db.conn -> 'a) -> 'a

with_connection conn k allows to wraps atomic low level accesses to the database from conn. with_connection can be used in the continuation of with_transaction.