sqlite — API Reference

SQLite support for Donna

sqlite

SQLite support for Donna.

Backed by the SQLite 3 amalgamation (vendored in ffi/).

import sqlite

case sqlite.open(":memory:"):
sqlite.Err(e) -> echo e
sqlite.Ok(db) ->
let _ = sqlite.exec(db, "CREATE TABLE users (id INTEGER, name TEXT)")
let _ = sqlite.exec(db, "INSERT INTO users VALUES (1, 'Donna')")
case sqlite.query(db, "SELECT id, name FROM users"):
sqlite.Err(e) -> echo e
sqlite.Ok(rows) -> echo "ok"
sqlite.close(db)

Types

pub type Db

An opaque handle to an open SQLite database.

Create with open, release with close.

Db(Int)

pub type Stmt

An opaque handle to a prepared SQLite statement.

Create with prepare, release with finalize.

Stmt(Int)

pub type Value

A value read from a result column.

import sqlite

pub fn describe(v: sqlite.Value) -> String:
  case v:
    sqlite.Null -> "null"
    sqlite.Int(n) -> "int"
    sqlite.Float(_) -> "float"
    sqlite.Text(s) -> "text: " <> s
    sqlite.Blob(_) -> "blob"

Null

Int(Int)

Float(Float)

Text(String)

Blob(String)

pub type Result(a)

The result of a SQLite operation.

Ok(a)

Err(String)

Functions

pub fn open(path: String) -> Result(Db)

Open a SQLite database at the given file path.

Pass ":memory:" for a temporary in-memory database.

import sqlite

pub fn example() -> sqlite.Result(sqlite.Db):
  sqlite.open(":memory:")

pub fn close(db: Db) -> Nil

Close a database and free its resources.

import sqlite

pub fn example(db: sqlite.Db) -> Nil:
  sqlite.close(db)

pub fn exec(db: Db, sql: String) -> Result(Nil)

Execute one or more SQL statements that produce no result rows.

Multiple statements may be separated by semicolons.

import sqlite

pub fn example(db: sqlite.Db) -> sqlite.Result(Nil):
  sqlite.exec(db, "CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)")

pub fn prepare(db: Db, sql: String) -> Result(Stmt)

Prepare a SQL statement for execution.

Use ? placeholders for parameters. Call finalize when done.

import sqlite

pub fn example(db: sqlite.Db) -> sqlite.Result(sqlite.Stmt):
  sqlite.prepare(db, "SELECT name FROM users WHERE id = ?")

pub fn bind_text(stmt: Stmt, idx: Int, value: String) -> Result(Nil)

Bind a text value to a prepared statement parameter (1-based index).

import sqlite

pub fn example(stmt: sqlite.Stmt) -> sqlite.Result(Nil):
  sqlite.bind_text(stmt, 1, "Donna")

pub fn bind_int(stmt: Stmt, idx: Int, value: Int) -> Result(Nil)

Bind an integer value to a prepared statement parameter (1-based index).

pub fn bind_float(stmt: Stmt, idx: Int, value: Float) -> Result(Nil)

Bind a float value to a prepared statement parameter (1-based index).

pub fn bind_null(stmt: Stmt, idx: Int) -> Result(Nil)

Bind a NULL value to a prepared statement parameter (1-based index).

pub fn step(stmt: Stmt) -> Result(Bool)

Advance a prepared statement to the next row.

Returns Ok(True) when a row is available, Ok(False) when all rows are exhausted, and Err on error.

import sqlite

pub fn example(stmt: sqlite.Stmt) -> sqlite.Result(Bool):
  sqlite.step(stmt)

pub fn column_count(stmt: Stmt) -> Int

Return the number of columns in the result set.

pub fn column(stmt: Stmt, idx: Int) -> Value

Read the value of a column in the current row (0-based index).

import sqlite

pub fn example(stmt: sqlite.Stmt) -> sqlite.Value:
  sqlite.column(stmt, 0)

pub fn column_name(stmt: Stmt, idx: Int) -> String

Return the declared name of a column (0-based index).

pub fn finalize(stmt: Stmt) -> Nil

Release a prepared statement and free its resources.

import sqlite

pub fn example(stmt: sqlite.Stmt) -> Nil:
  sqlite.finalize(stmt)

pub fn reset(stmt: Stmt) -> Nil

Reset a prepared statement so it can be re-executed.

Bound parameter values are retained. Call bind_* again to change them.

pub fn last_insert_rowid(db: Db) -> Int

Return the rowid of the last successful INSERT.

pub fn changes(db: Db) -> Int

Return the number of rows changed by the last INSERT, UPDATE, or DELETE.

pub fn query(db: Db, sql: String) -> Result(List(List(Value)))

Execute a SELECT and collect all rows.

Each row is a List(Value) with one entry per column, in column order.

import sqlite

pub fn example(db: sqlite.Db) -> sqlite.Result(List(List(sqlite.Value))):
  sqlite.query(db, "SELECT id, name FROM users")

pub fn is_ok(r: Result(a)) -> Bool

Return True when a Result is Ok.

pub fn is_err(r: Result(a)) -> Bool

Return True when a Result is Err.

pub fn unwrap_string(r: Result(String)) -> String

Extract the string from an Ok, or a tagged error string.

pub fn unwrap_int(r: Result(Int)) -> Int

Extract the int from an Ok, or 0 on error.