sqlight

Types

pub type Connection
pub type Error {
  SqlightError(code: ErrorCode, message: String, offset: Int)
}

Constructors

  • SqlightError(code: ErrorCode, message: String, offset: Int)

    Arguments

    • offset

      If the most recent error references a specific token in the input SQL, this is the byte offset of the start of that token. If the most recent error does not reference a specific token, this is -1.

The errors that SQLite can return.

See the SQLite documentation for further details. https://sqlite.org/rescode.html

When running on JavaScript with Deno only a less-detailed subset of these will be used as the underlying library does not expose extended error codes.

pub type ErrorCode {
  Abort
  Auth
  Busy
  Cantopen
  Constraint
  Corrupt
  Done
  Empty
  GenericError
  Format
  Full
  Internal
  Interrupt
  Ioerr
  Locked
  Mismatch
  Misuse
  Nolfs
  Nomem
  Notadb
  Notfound
  Notice
  GenericOk
  Perm
  Protocol
  Range
  Readonly
  Row
  Schema
  Toobig
  Warning
  AbortRollback
  AuthUser
  BusyRecovery
  BusySnapshot
  BusyTimeout
  CantopenConvpath
  CantopenDirtywal
  CantopenFullpath
  CantopenIsdir
  CantopenNotempdir
  CantopenSymlink
  ConstraintCheck
  ConstraintCommithook
  ConstraintDatatype
  ConstraintForeignkey
  ConstraintFunction
  ConstraintNotnull
  ConstraintPinned
  ConstraintPrimarykey
  ConstraintRowid
  ConstraintTrigger
  ConstraintUnique
  ConstraintVtab
  CorruptIndex
  CorruptSequence
  CorruptVtab
  ErrorMissingCollseq
  ErrorRetry
  ErrorSnapshot
  IoerrAccess
  IoerrAuth
  IoerrBeginAtomic
  IoerrBlocked
  IoerrCheckreservedlock
  IoerrClose
  IoerrCommitAtomic
  IoerrConvpath
  IoerrCorruptfs
  IoerrData
  IoerrDelete
  IoerrDeleteNoent
  IoerrDirClose
  IoerrDirFsync
  IoerrFstat
  IoerrFsync
  IoerrGettemppath
  IoerrLock
  IoerrMmap
  IoerrNomem
  IoerrRdlock
}

Constructors

  • Abort
  • Auth
  • Busy
  • Cantopen
  • Constraint
  • Corrupt
  • Done
  • Empty
  • GenericError
  • Format
  • Full
  • Internal
  • Interrupt
  • Ioerr
  • Locked
  • Mismatch
  • Misuse
  • Nolfs
  • Nomem
  • Notadb
  • Notfound
  • Notice
  • GenericOk
  • Perm
  • Protocol
  • Range
  • Readonly
  • Row
  • Schema
  • Toobig
  • Warning
  • AbortRollback
  • AuthUser
  • BusyRecovery
  • BusySnapshot
  • BusyTimeout
  • CantopenConvpath
  • CantopenDirtywal
  • CantopenFullpath
  • CantopenIsdir
  • CantopenNotempdir
  • CantopenSymlink
  • ConstraintCheck
  • ConstraintCommithook
  • ConstraintDatatype
  • ConstraintForeignkey
  • ConstraintFunction
  • ConstraintNotnull
  • ConstraintPinned
  • ConstraintPrimarykey
  • ConstraintRowid
  • ConstraintTrigger
  • ConstraintUnique
  • ConstraintVtab
  • CorruptIndex
  • CorruptSequence
  • CorruptVtab
  • ErrorMissingCollseq
  • ErrorRetry
  • ErrorSnapshot
  • IoerrAccess
  • IoerrAuth
  • IoerrBeginAtomic
  • IoerrBlocked
  • IoerrCheckreservedlock
  • IoerrClose
  • IoerrCommitAtomic
  • IoerrConvpath
  • IoerrCorruptfs
  • IoerrData
  • IoerrDelete
  • IoerrDeleteNoent
  • IoerrDirClose
  • IoerrDirFsync
  • IoerrFstat
  • IoerrFsync
  • IoerrGettemppath
  • IoerrLock
  • IoerrMmap
  • IoerrNomem
  • IoerrRdlock
pub type Stats {
  Stats(used: Int, highwater: Int)
}

Constructors

  • Stats(used: Int, highwater: Int)

A value that can be sent to SQLite as one of the arguments to a parameterised SQL query.

pub type Value

Functions

pub fn blob(value: BitArray) -> Value

Convert a Gleam BitString to an SQLite blob, to be used an argument to a query.

pub fn bool(value: Bool) -> Value

Convert a Gleam Bool to an SQLite int, to be used an argument to a query.

SQLite does not have a native boolean type. Instead, it uses ints, where 0 is False and 1 is True. Because of this the Gleam stdlib decoder for bools will not work, instead the decode_bool function should be used as it supports both ints and bools.

pub fn close(connection: Connection) -> Result(Nil, Error)

Close a connection to a SQLite database.

Ideally applications should finallise all prepared statements and other open resources before closing a connection. See the SQLite documentation for more information: https://www.sqlite.org/c3ref/close.html.

pub fn decode_bool(
  value: Dynamic,
) -> Result(Bool, List(DecodeError))

Decode an SQLite boolean value.

Decodes 0 as False and any other integer as True.

pub fn error_code_from_int(code: Int) -> ErrorCode

Convert an error code int to an Error.

If the code is not a known error code, GenericError is returned.

pub fn error_code_to_int(error: ErrorCode) -> Int

Convert an Error to an error code int.

See the SQLite documentation for the full list of error codes. https://sqlite.org/rescode.html

pub fn exec(
  sql: String,
  on connection: Connection,
) -> Result(Nil, Error)
pub fn float(value: Float) -> Value

Convert a Gleam Float to an SQLite float, to be used an argument to a query.

pub fn int(value: Int) -> Value

Convert a Gleam Int to an SQLite int, to be used an argument to a query.

pub fn null() -> Value

Construct an SQLite null, to be used an argument to a query.

pub fn nullable(
  inner_type: fn(a) -> Value,
  value: Option(a),
) -> Value

Convert a Gleam Option to an SQLite nullable value, to be used an argument to a query.

pub fn open(path: String) -> Result(Connection, Error)

Open a connection to a SQLite database.

URI filenames are supported by SQLite, making it possible to open read-only databases, in memory databases, and more. Further information about this can be found in the SQLite documentation: https://sqlite.org/uri.html.

Examples

Open “data.db” in the current working directory

let assert Ok(conn) = open("file:data.sqlite3")

Opens “data.db” in read only mode with a private cache

let assert Ok(conn) = open("file:data.db?mode=ro&cache=private")

Opens a shared memory database named memdb1 with a shared cache.

let assert Ok(conn) = open("file:memdb1?mode=memory&cache=shared")
pub fn query(
  sql: String,
  on connection: Connection,
  with arguments: List(Value),
  expecting decoder: fn(Dynamic) -> Result(a, List(DecodeError)),
) -> Result(List(a), Error)
pub fn text(value: String) -> Value

Convert a Gleam String to an SQLite text, to be used an argument to a query.

pub fn with_connection(path: String, f: fn(Connection) -> a) -> a

Open a connection to a SQLite database and execute a function with it, then close the connection.

This function works well with a use expression to automatically close the connection at the end of a block.

Crashes

This function crashes if the connection cannot be opened or closed.

Examples

use conn <- with_connection("file:mydb?mode=memory")
// Use the connection here...
Search Document