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 ¶
- func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration, ...) error
- func RowInt(row SqliteRow, column string) (int64, error)
- func ValidateSqliteSchemaPrefix(prefix string) error
- type ApplySqliteMigrationsOptions
- type SqliteDatabase
- type SqliteExecutor
- type SqliteMigration
- type SqliteRow
- type SqliteValue
- type TextReader
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 ValidateSqliteSchemaPrefix ¶
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
RunCounted(sql string, params ...SqliteValue) (int64, 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, RunCounted, Get, and All execute one statement with positional bindings. RunCounted runs one like Run and returns the rows it inserted, updated or deleted, as SQLite's changes() counts them (index writes and rows changed by triggers do not count); it may cost a statement more than Run, so callers that need no count use Run. 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 ¶
SqliteMigration is one immutable schema version and the statements that create it from the previous version.
type SqliteRow ¶
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. |
|
Package sqlitetest holds the helpers the Chord SQLite driver tests share.
|
Package sqlitetest holds the helpers the Chord SQLite driver tests share. |