Readme

sigil-sqlite

SQLite database bindings for Sigil.

Embeddable SQLite access backed by the SQLite amalgamation compiled in-tree. Suitable for application data, local caches, and anywhere a full relational database is overkill.

Modules

Module	Purpose
`(sigil sqlite)`	SQLite database bindings (low + high API)

API summary

Database

Procedure	Purpose
`sqlite-open`	Open database (or `":memory:"`)
`sqlite-close`	Close a database handle
`sqlite-exec`	Execute a SQL string (DDL, simple queries)
`call-with-database`	Open + run a proc + close, with cleanup

Prepared statements

Procedure	Purpose
`sqlite-prepare`	Compile a SQL statement
`sqlite-bind`	Bind a parameter (1-based index)
`sqlite-step`	Advance: `'row`, `'done`, or `#f`
`sqlite-reset`	Reset a statement to its initial state
`sqlite-finalize`	Free a statement

Column access

Procedure	Purpose
`sqlite-column-count`	Number of columns in the current row
`sqlite-column-name`	Column name by 0-based index
`sqlite-column`	Column value by 0-based index

Database info

Procedure	Purpose
`sqlite-last-insert-rowid`	rowid of the last insert
`sqlite-changes`	Rows changed by the last statement
`sqlite-errmsg`	Last error message

Read the rest

High-level helpers

Procedure	Purpose
`sqlite-query`	Run query; return all rows as alists
`sqlite-query-row`	Run query; return first row or `#f`
`sqlite-run`	Run INSERT/UPDATE/DELETE with parameters

Predicates

Procedure	Purpose
`sqlite-db?`	SQLite database handle predicate
`sqlite-stmt?`	Prepared statement predicate

System prerequisites

None beyond a working C toolchain. The SQLite amalgamation (vendor/sqlite3.c + vendor/sqlite3.h) is vendored and compiled in-tree with these build flags:

-DSQLITE_THREADSAFE=0
-DSQLITE_OMIT_LOAD_EXTENSION
-DSQLITE_ENABLE_FTS5

Dependencies

sigil-stdlib

Build

sigil deps install
sigil build
sigil test --report

The first build compiles the SQLite amalgamation (one large translation unit) plus native/sqlite.c. Subsequent builds hit the cache.

Usage

(import (sigil sqlite))

(call-with-database "app.db"
  (lambda (db)
    (sqlite-exec db "CREATE TABLE IF NOT EXISTS users
                       (id INTEGER PRIMARY KEY, name TEXT)")
    (sqlite-run db "INSERT INTO users (name) VALUES (?)" "Alice")
    (sqlite-query db "SELECT * FROM users")))
;; => (((id . 1) (name . "Alice")))