Sqlite

Sqlite :: # (opaque)

Execute SQLite statements and decode rows using either one-shot or reusable prepared APIs. Application code works with the public Value, Binding, Stmt, and ErrCode types below; raw host ABI records remain internal.

Database paths use basic-cli's byte-preserving Path type. See the host runtime behavior for connection caching and lifetime details.

names = Sqlite.query_many!({
	path: "people.db",
	query: "SELECT name FROM people WHERE active = :active",
	bindings: [{ name: ":active", value: Integer(1) }],
	rows: Sqlite.str("name"),
})?

prepare! : { path : Path, query : Str } => Try(Stmt, [SqliteErr(ErrCode, Str)])

Prepare a Stmt for reuse by the prepared execute and query operations.

execute! : { path : Path, query : Str, bindings : List(Binding) } => Try({}, [RowsReturnedUseQueryInstead, SqliteErr(ErrCode, Str)])

Execute a SQL statement that doesn't return any rows (INSERT/UPDATE/DELETE).

query! : { bindings : List(Binding), path : Path, query : Str, row : List(Str) -> (SqliteStmt -> Try(ok, [SqliteErr(ErrCode, Str), ..[NoRowsReturned, TooManyRowsReturned]])) } => Try(ok, [SqliteErr(ErrCode, Str), ..[NoRowsReturned, TooManyRowsReturned]])

Execute a SQL query and decode exactly one row into a value. bindings is a List(Binding) and row is a decoder built from the functions below.

query_many! : { bindings : List(Binding), path : Path, query : Str, rows : List(Str) -> (SqliteStmt -> [Err([SqliteErr(ErrCode, Str)]), Ok(a)]) } => Try(List(a), [SqliteErr(ErrCode, Str)])

Execute a SQL query and decode multiple rows into a list of values. bindings is a List(Binding) and rows is a row decoder.

decode_record : (a -> (b -> [Ok(c), Err(d)])), (a -> (b -> [Ok(e), Err(d)])), (c, e -> f) -> (a -> (b -> [Err(d), ..[Ok(f)]]))

Decode a Sqlite row into a record by combining two decoders.

map_value : (a -> (b -> [Ok(c), Err(d)])), (c -> e) -> (a -> (b -> [Ok(e), Err(d)]))

Transform the output of a decoder by applying a function to the decoded value.

map_value_result : (a -> (b -> [Ok(c), Err(d)])), (c -> [Err(d)]) -> (a -> (b -> [Err(d)]))

Transform a decoder's output with a function returning a Try.

tagged_value : a -> (List(a) -> (SqliteStmt => Try(SqliteValue, [NoSuchField(a), SqliteErr(ErrCode, Str)]))) where [a.is_eq : a, a -> Bool]

Decode a Value keeping it tagged.

str : a -> (List(a) -> (SqliteStmt => [Err([UnexpectedType([Bytes, Integer, Null, Real, String]), NoSuchField(a), SqliteErr(ErrCode, Str)]), ..[Ok(Str)]])) where [a.is_eq : a, a -> Bool]

Decode a column to a Str.

bytes : a -> (List(a) -> (SqliteStmt => [Err([UnexpectedType([Bytes, Integer, Null, Real, String]), NoSuchField(a), SqliteErr(ErrCode, Str)]), ..[Ok(List(U8))]])) where [a.is_eq : a, a -> Bool]

Decode a column to a [List U8].

i64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String])]), Ok(I64)])) where [a.is_eq : a, a -> Bool]

Decode a column to an I64.

i32 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(I32)]])) where [a.is_eq : a, a -> Bool]

Decode a column to an I32.

i16 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(I16)]])) where [a.is_eq : a, a -> Bool]

Decode a column to an I16.

i8 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(I8)]])) where [a.is_eq : a, a -> Bool]

Decode a column to an I8.

u64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(U64)]])) where [a.is_eq : a, a -> Bool]

Decode a column to a U64.

u32 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(U32)]])) where [a.is_eq : a, a -> Bool]

Decode a column to a U32.

u16 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(U16)]])) where [a.is_eq : a, a -> Bool]

Decode a column to a U16.

u8 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok(U8)]])) where [a.is_eq : a, a -> Bool]

Decode a column to a U8.

f64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String])]), Ok(F64)])) where [a.is_eq : a, a -> Bool]

Decode a column to an F64.

nullable_str : a -> (List(a) -> (SqliteStmt => [Err([UnexpectedType([Bytes, Integer, Null, Real, String]), NoSuchField(a), SqliteErr(ErrCode, Str)]), ..[Ok([NotNull(Str), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(Str), Null].

nullable_bytes : a -> (List(a) -> (SqliteStmt => [Err([UnexpectedType([Bytes, Integer, Null, Real, String]), NoSuchField(a), SqliteErr(ErrCode, Str)]), ..[Ok([NotNull(List(U8)), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(List(U8)), Null].

nullable_i64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String])]), ..[Ok([NotNull(I64), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(I64), Null].

nullable_i32 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(I32), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(I32), Null].

nullable_i16 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(I16), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(I16), Null].

nullable_i8 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(I8), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(I8), Null].

nullable_u64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(U64), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(U64), Null].

nullable_u32 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(U32), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(U32), Null].

nullable_u16 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(U16), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(U16), Null].

nullable_u8 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String]), IntOutOfBounds]), ..[Ok([NotNull(U8), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(U8), Null].

nullable_f64 : a -> (List(a) -> (SqliteStmt => [Err([NoSuchField(a), SqliteErr(ErrCode, Str), UnexpectedType([Bytes, Integer, Null, Real, String])]), ..[Ok([NotNull(F64), Null])]])) where [a.is_eq : a, a -> Bool]

Decode a nullable column to [NotNull(F64), Null].

errcode_to_str : [Abort, AuthDenied, Busy, CanNotOpen, Constraint, Corrupt, Done, Empty, Error, Format, Full, IOErr, Internal, Interrupt, Locked, Mismatch, Misuse, NoLFS, NoMem, NotADatabase, NotFound, Notice, OutOfRange, Perm, Protocol, ReadOnly, Row, Schema, TooBig, Warning, Unknown(I64)] -> Str

Convert an ErrCode to a pretty string for display purposes.

Value : [
    Null,
    Real(F64),
    Integer(I64),
    String(Str),
    Bytes(List(U8)),
]

A value accepted by a SQLite binding or returned from a column.

Binding : {
    name : Str,
    value : Value,
}

A named parameter binding. Include SQLite's parameter prefix in name, for example { name: ":id", value: Integer(42) }.

Stmt

Sqlite.Stmt :: # (opaque)

Represents a prepared statement that can be executed many times.

to_inspect : Stmt -> Str

Render the statement without exposing its host handle.

execute! : Stmt, List(Binding) => Try({}, [RowsReturnedUseQueryInstead, SqliteErr(ErrCode, Str)])

Execute this prepared statement without returning rows.

query! : Stmt, List(Binding), (List(Str) -> (SqliteStmt -> Try(ok, [SqliteErr(ErrCode, Str), ..[NoRowsReturned, TooManyRowsReturned]]))) => Try(ok, [SqliteErr(ErrCode, Str), ..[NoRowsReturned, TooManyRowsReturned]])

Execute this prepared query and decode exactly one row.

query_many! : Stmt, List(Binding), (List(Str) -> (SqliteStmt -> [Err([SqliteErr(ErrCode, Str)]), Ok(a)])) => Try(List(a), [SqliteErr(ErrCode, Str)])

Execute this prepared query and decode all returned rows.

ErrCode : [
    Error,
    Internal,
    Perm,
    Abort,
    Busy,
    Locked,
    NoMem,
    ReadOnly,
    Interrupt,
    IOErr,
    Corrupt,
    NotFound,
    Full,
    CanNotOpen,
    Protocol,
    Empty,
    Schema,
    TooBig,
    Constraint,
    Mismatch,
    Misuse,
    NoLFS,
    AuthDenied,
    Format,
    OutOfRange,
    NotADatabase,
    Notice,
    Warning,
    Row,
    Done,
    Unknown(I64),
]

Represents various error codes that can be returned by Sqlite.

DecodeErr : [NoSuchField(Str), SqliteErr(ErrCode, Str)]

Documented shape of the errors a decoder can produce (the decoders below are left unannotated and infer a subset of these structurally):

[
    NoSuchField(Str),
    SqliteErr(ErrCode, Str),
    UnexpectedType([Integer, Real, String, Bytes, Null]),
    FailedToDecodeInteger,
    FailedToDecodeReal,
    IntOutOfBounds,
    NoRowsReturned,
    TooManyRowsReturned,
]