sqlite

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package sqlite ports Pi's @earendil-works/chord/sqlite: the portable SQLite database facade, the atomic migration runner and schema-prefix validation that durable storage and other Chord hosts share. It imports no SQLite driver; chord/sqlite/node and chord/sqlite/cloudflare adapt a concrete connection.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplySqliteMigrations

func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration, options ApplySqliteMigrationsOptions) error

ApplySqliteMigrations applies every pending migration atomically, tracking the applied version in the metadata table options.Table names. The table name must pass ValidateSqliteSchemaPrefix and the versions must run 1, 2, 3...; both are checked before the database is touched.

func RowInt

func RowInt(row SqliteRow, column string) (int64, error)

RowInt reads an INTEGER column of a row.

func ValidateSqliteSchemaPrefix

func ValidateSqliteSchemaPrefix(prefix string) error

ValidateSqliteSchemaPrefix checks a prefix before it becomes part of a SQLite identifier: it must be an identifier and must not begin with SQLite's reserved `sqlite_` (any case).

Types

type ApplySqliteMigrationsOptions

type ApplySqliteMigrationsOptions struct {
	Table string
}

ApplySqliteMigrationsOptions names the metadata table the applied version is tracked in.

type SqliteDatabase

type SqliteDatabase interface {
	SqliteExecutor
	Transaction(callback func(transaction SqliteExecutor) error) error
	Close() error
}

SqliteDatabase is the minimal portable SQLite database facade.

Every operation blocks until it settles, so adapters may execute outside the caller's goroutine.

Transaction passes the callback a transaction handle. All work in the transaction must use that handle; the handle is invalid after the callback returns. Adapters must queue unrelated operations and other transactions until the transaction finishes, in call order. Transaction returns after commit or rollback. Calling the database itself (including Transaction or Close) from inside a callback therefore waits for that transaction and never returns.

When the callback fails, the adapter must roll the transaction back before returning that same error. If rollback fails, it must return a different error that does not unwrap to the callback error, so callers cannot mistake the callback error for a guaranteed rollback.

type SqliteExecutor

type SqliteExecutor interface {
	Exec(sql string) error
	Run(sql string, params ...SqliteValue) error
	Get(sql string, params ...SqliteValue) (SqliteRow, error)
	All(sql string, params ...SqliteValue) ([]SqliteRow, error)
}

SqliteExecutor is the SQL surface shared by a database and its transaction handles.

Exec runs SQL text without bindings and may contain several statements. Run, Get, and All execute one statement with positional bindings. Adapters may cache prepared statements by SQL text, so callers pass values as bindings instead of interpolating them. Get returns a nil row when the statement yields none.

type SqliteMigration

type SqliteMigration struct {
	Version    int
	Statements []string
}

SqliteMigration is one immutable schema version and the statements that create it from the previous version.

type SqliteRow

type SqliteRow = map[string]any

SqliteRow is one result row keyed by column name. INTEGER columns are int64, REAL columns float64, TEXT columns string, BLOB columns []byte, and NULL nil.

type SqliteValue

type SqliteValue = any

SqliteValue is a value supported by the portable SQLite drivers: nil, int64 (or any Go integer), float64, string, or []byte.

type TextReader

type TextReader interface {
	EachText(sql string, params []SqliteValue, fn func(text []byte) error) error
}

TextReader is implemented by a database that can hand the first column of each result row to a callback as the row is read, without building rows. The bytes are valid until the callback returns. Readers of many rows use it to avoid a map and a copy per row; the callback must not call the database. pig additive (D104): row reading without per-row maps has no Pi counterpart.

Directories

Path Synopsis
Package cloudflare adapts the SQLite storage of a Cloudflare Durable Object to the portable Chord SQLite facade.
Package cloudflare adapts the SQLite storage of a Cloudflare Durable Object to the portable Chord SQLite facade.
Package node adapts a native SQLite connection to the portable Chord SQLite facade.
Package node adapts a native SQLite connection to the portable Chord SQLite facade.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL