AtlatestRepositorysigil-sqlite

sigil-sqlite / treeREADME.md

Read it rendered

1# sigil-sqlite
2
3SQLite database bindings for [Sigil](https://codeberg.org/sigil/sigil).
4
5Embeddable SQLite access backed by the SQLite amalgamation compiled
6in-tree. Suitable for application data, local caches, and anywhere a
7full relational database is overkill.
8
9## Modules
11| Module | Purpose |
12|-------------------|-------------------------------------------|
13| `(sigil sqlite)` | SQLite database bindings (low + high API) |
15## API summary
17### Database
19| Procedure | Purpose |
20|-----------------------------|---------------------------------------------|
21| `sqlite-open` | Open database (or `":memory:"`) |
22| `sqlite-close` | Close a database handle |
23| `sqlite-exec` | Execute a SQL string (DDL, simple queries) |
24| `call-with-database` | Open + run a proc + close, with cleanup |
26### Prepared statements
28| Procedure | Purpose |
29|-----------------------------|---------------------------------------------|
30| `sqlite-prepare` | Compile a SQL statement |
31| `sqlite-bind` | Bind a parameter (1-based index) |
32| `sqlite-step` | Advance: `'row`, `'done`, or `#f` |
33| `sqlite-reset` | Reset a statement to its initial state |
34| `sqlite-finalize` | Free a statement |
36### Column access
38| Procedure | Purpose |
39|-----------------------------|---------------------------------------------|
40| `sqlite-column-count` | Number of columns in the current row |
41| `sqlite-column-name` | Column name by 0-based index |
42| `sqlite-column` | Column value by 0-based index |
44### Database info
46| Procedure | Purpose |
47|-----------------------------|---------------------------------------------|
48| `sqlite-last-insert-rowid` | rowid of the last insert |
49| `sqlite-changes` | Rows changed by the last statement |
50| `sqlite-errmsg` | Last error message |
52### High-level helpers
54| Procedure | Purpose |
55|-----------------------------|---------------------------------------------|
56| `sqlite-query` | Run query; return all rows as alists |
57| `sqlite-query-row` | Run query; return first row or `#f` |
58| `sqlite-run` | Run INSERT/UPDATE/DELETE with parameters |
60### Predicates
62| Procedure | Purpose |
63|--------------------|-----------------------------------|
64| `sqlite-db?` | SQLite database handle predicate |
65| `sqlite-stmt?` | Prepared statement predicate |
67## System prerequisites
69None beyond a working C toolchain. The SQLite amalgamation
70(`vendor/sqlite3.c` + `vendor/sqlite3.h`) is vendored and compiled
71in-tree with these build flags:
73- `-DSQLITE_THREADSAFE=0`
74- `-DSQLITE_OMIT_LOAD_EXTENSION`
75- `-DSQLITE_ENABLE_FTS5`
77## Dependencies
79- sigil-stdlib
81## Build
83```sh
84sigil deps install
85sigil build
86sigil test --report
87```
89The first build compiles the SQLite amalgamation (one large
90translation unit) plus `native/sqlite.c`. Subsequent builds hit the
91cache.
93## Usage
95```scheme
96(import (sigil sqlite))
98(call-with-database "app.db"
99 (lambda (db)
100 (sqlite-exec db "CREATE TABLE IF NOT EXISTS users
101 (id INTEGER PRIMARY KEY, name TEXT)")
102 (sqlite-run db "INSERT INTO users (name) VALUES (?)" "Alice")
103 (sqlite-query db "SELECT * FROM users")))
104;; => (((id . 1) (name . "Alice")))
105```
107## License
109BSD-3-Clause.
111Vendored SQLite (under `vendor/`) is public domain. See
112`vendor/sqlite3.c` for the SQLite blessing.