hot.dev/hot-std / ::hot::sqlite

SQLite databases, embedded in the runtime (no server, no wire protocol). Respects file.mode:

• direct (CLI default) — path is a host filesystem path, opened in place.
• service (managed default) — path names a file in managed storage. Opening checks the database out into a local scratch copy; queries run at local speed; close/sync commit the bytes back. Commits are an atomic compare-and-swap on the stored file's version: when the file changed since checkout, the commit loses cleanly with an Err (reopen and retry) — never a silent overwrite. A crash between commits loses writes since the last sync, and commit cost is proportional to the file size, so service mode fits small, session-shaped workloads; high-frequency writers belong on a server database (see hot.dev/pg).

Most callers should use the ::sql package's sqlite driver rather than these functions directly — it adds placeholder compilation, typed queries, and transactions.

Example

conn ::hot::sqlite/open("/tmp/app.db")
::hot::sqlite/execute(conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)", [])
::hot::sqlite/execute(conn, "INSERT INTO t (name) VALUES (?)", ["Ada"])
rows ::hot::sqlite/query(conn, "SELECT * FROM t WHERE name = ?", ["Ada"])
::hot::sqlite/close(conn)

Functions

close

fn (conn: Any): Bool

Close the connection. In service mode this commits the checkout first (an Err leaves the connection open so data can be read back out) and removes the scratch copy. Idempotent.

execute

fn (conn: Any, sql: Str, params: Vec): Map

Run one statement (INSERT/UPDATE/DELETE/DDL) with ? positional parameters. Returns {rows-affected, last-insert-id} or an Err. One statement per call; parameter count must match the statement. Bindable types: Int, Dec, Str, Bytes, Bool (as 0/1), null.

open

fn (path-or-options: Str | Map): Any

Open a SQLite database. Pass a path string, or an options map:

• path — the database file (host path in direct mode, managed storage path in service mode). Created if missing (unless read-only).
• read-only — open without write access; in service mode this skips the commit entirely (and never uploads).

Returns a connection handle, or an Err. Foreign keys are ON and the busy timeout is 5s.

query

fn (conn: Any, sql: Str, params: Vec): Vec

Run one SELECT with ? positional parameters. Returns a Vec of row Maps keyed by column name, or an Err. Column types map to Int, Dec (REAL), Str, Bytes (BLOB), and null.

sync

fn (conn: Any): Bool

Commit the service-mode checkout back to managed storage without closing (durability point for long-lived connections). No-op in direct mode and for read-only opens. Errs on conflict — the stored file changed since checkout.