sqlite

Reads and writes SQLite databases.

SQL is a template, never a string

Every SQL argument in this module is a formatted sequence -- a t"..." -- and passing a plain Str raises. Only a template's literal text becomes SQL; an interpolated value is bound as a parameter, and ${#name} leaves a hole for a prepared statement to fill at each call. See Parameter Binding.

VFS support

This API is partially VFS-aware. It opens databases over the Unix socket transport on Unix hosts, so docker.with and sudo.with work. Remote transports and Windows UAC elevation are not supported.

Types

Type	Description
Busy	Raised when an operation fails because the database is locked by another connection or process.
Connection	An open database connection.
Error	Raised when a SQLite operation fails for any reason other than the database being locked.
Row	A single result row.
Statement	A compiled SQL statement that can be run repeatedly with different parameters.
Transaction	A database transaction in progress.

Functions

open path … -> Connection

Opens a database connection, creating the database if it does not exist.

Parameters

Name	Type	Description
path	(Str | fs.Path)	Path to the database file, or ":memory:" for a private in-memory database. A relative path resolves against the current directory of the active VFS context.
:retries?	Int	Attempts to retry an operation that fails because the database is busy. Defaults to 10; 0 disables retrying. See Busy retry.
:min_wait?	Int	Milliseconds to wait before the first retry. Defaults to 1.
:max_wait?	Int	Ceiling in milliseconds for the doubling retry wait. Defaults to 1000.

Example

# Explicit handle
let conn = open mydb.sqlite
conn.close()

# Block form, closed on return
open mydb.sqlite do |conn|
  conn.execute
    t"CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
  conn.execute t"INSERT INTO users (name) VALUES (${#name})" name: "Alice"

# An in-memory database, discarded when it closes
open ":memory:" do |conn|
  conn.execute t"CREATE TABLE scratch (n INTEGER)"

open[R] path func … -> R

Opens a database connection and calls func with it. The connection is closed when func returns.

Parameters

Name	Type	Description
path	(Str | fs.Path)	Path to the database file, or ":memory:" for a private in-memory database. A relative path resolves against the current directory of the active VFS context.
:retries?	Int	Attempts to retry an operation that fails because the database is busy. Defaults to 10; 0 disables retrying. See Busy retry.
:min_wait?	Int	Milliseconds to wait before the first retry. Defaults to 1.
:max_wait?	Int	Ceiling in milliseconds for the doubling retry wait. Defaults to 1000.
func	((Connection) -> R)	Called with the Connection.