Documentation
¶
Overview ¶
Package sqlite is the portable SQLite storage core of pi-durable: the database facade, the schema migrations, and SqliteStorage. It imports no SQLite driver; durable/storage/sqlite/node adapts a concrete connection.
Index ¶
- Variables
- func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration) error
- type SqliteDatabase
- type SqliteExecutor
- type SqliteMigration
- type SqliteRow
- type SqliteStorage
- func (storage *SqliteStorage) Close(_ context.Context) error
- func (storage *SqliteStorage) Commit(_ context.Context, batch []durable.StorageWrite) (durable.Seq, error)
- func (storage *SqliteStorage) Conversation(_ context.Context, id durable.ConversationId) (*durable.ConversationRecord, error)
- func (storage *SqliteStorage) Document(_ context.Context, id durable.DocumentId, at durable.DocumentPoint) (*durable.StoredDocument, error)
- func (storage *SqliteStorage) Entry(_ context.Context, id durable.EntryId) (*durable.EntryAt, error)
- func (storage *SqliteStorage) FindDocument(_ context.Context, address durable.DocumentAddress, at durable.DocumentPoint) (*durable.DocumentRecord, error)
- func (storage *SqliteStorage) FindLatestHeadMarker(_ context.Context, conversationId durable.ConversationId, ...) (*durable.EntryRecord, error)
- func (storage *SqliteStorage) MintId() (int64, error)
- func (storage *SqliteStorage) ScanConversations(_ context.Context, query durable.ConversationQuery, limit int, ...) (durable.Page[durable.ConversationRecord, durable.Cursor], error)
- func (storage *SqliteStorage) ScanDocuments(_ context.Context, query durable.DocumentQuery, limit int, ...) (durable.Page[durable.DocumentRecord, durable.Cursor], error)
- func (storage *SqliteStorage) ScanEntries(_ context.Context, query durable.EntryQuery, limit int, cursor durable.Cursor) (durable.Page[durable.EntryRecord, durable.Cursor], error)
- func (storage *SqliteStorage) ScanSubmissions(_ context.Context, query durable.SubmissionQuery, limit int, ...) (durable.Page[durable.SubmissionRecord, durable.Cursor], error)
- func (storage *SqliteStorage) ScanTasks(_ context.Context, query durable.TaskQuery, limit int, cursor durable.Cursor) (durable.Page[storedTask, durable.Cursor], error)
- func (storage *SqliteStorage) Submission(_ context.Context, id durable.SubmissionId) (*durable.SubmissionRecord, error)
- func (storage *SqliteStorage) SubmissionByRequest(_ context.Context, conversationId durable.ConversationId, requestId string) (*durable.SubmissionRecord, error)
- func (storage *SqliteStorage) Task(_ context.Context, id durable.TaskId) (*storedTask, error)
- func (storage *SqliteStorage) VisibleEntry(_ context.Context, conversationId durable.ConversationId, id durable.EntryId) (*durable.EntryAt, error)
- type SqliteValue
Constants ¶
This section is empty.
Variables ¶
var CurrentSqliteSchemaVersion = lastVersion(SqliteMigrations)
CurrentSqliteSchemaVersion is the version of the last migration in SqliteMigrations.
var SqliteMigrations = []SqliteMigration{{Version: 1, Statements: initialSchema}}
SqliteMigrations is the immutable, ordered schema history. Append new migrations after the initial schema ships.
Functions ¶
func ApplySqliteMigrations ¶
func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration) error
ApplySqliteMigrations applies all pending schema migrations atomically. A nil migrations slice selects SqliteMigrations; a non-nil empty slice applies none.
Types ¶
type SqliteDatabase ¶
type SqliteDatabase interface {
SqliteExecutor
Transaction(callback func(transaction SqliteExecutor) error) error
Close() error
}
SqliteDatabase is the minimal database facade required by SqliteStorage.
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 ¶
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 SqliteStorage ¶
type SqliteStorage struct {
// contains filtered or unexported fields
}
SqliteStorage is the portable SQLite implementation of durable.Storage over a SqliteDatabase facade.
func Open ¶
func Open(db SqliteDatabase) (*SqliteStorage, error)
Open initializes storage over an owned SQLite database facade. A failure closes the database.
func (*SqliteStorage) Close ¶
func (storage *SqliteStorage) Close(_ context.Context) error
Close waits for admitted multi-query reads, then closes the database. Every call returns the same result once the database is closed.
func (*SqliteStorage) Commit ¶
func (storage *SqliteStorage) Commit(_ context.Context, batch []durable.StorageWrite) (durable.Seq, error)
Commit atomically persists one batch and returns its sequence.
func (*SqliteStorage) Conversation ¶
func (storage *SqliteStorage) Conversation( _ context.Context, id durable.ConversationId, ) (*durable.ConversationRecord, error)
Conversation looks up one conversation by exact ID.
func (*SqliteStorage) Document ¶
func (storage *SqliteStorage) Document( _ context.Context, id durable.DocumentId, at durable.DocumentPoint, ) (*durable.StoredDocument, error)
Document materializes one specific incarnation by ID at the selected point without following a replacement at its address.
func (*SqliteStorage) Entry ¶
func (storage *SqliteStorage) Entry(_ context.Context, id durable.EntryId) (*durable.EntryAt, error)
Entry looks up one global entry and the sequence of the commit that persisted it.
func (*SqliteStorage) FindDocument ¶
func (storage *SqliteStorage) FindDocument( _ context.Context, address durable.DocumentAddress, at durable.DocumentPoint, ) (*durable.DocumentRecord, error)
FindDocument resolves the incarnation occupying one exact logical address at the selected point.
func (*SqliteStorage) FindLatestHeadMarker ¶
func (storage *SqliteStorage) FindLatestHeadMarker( _ context.Context, conversationId durable.ConversationId, atOrBeforeEntryId *durable.EntryId, ) (*durable.EntryRecord, error)
FindLatestHeadMarker returns the newest visible entry with a head at or below the optional inclusive cutoff.
func (*SqliteStorage) MintId ¶
func (storage *SqliteStorage) MintId() (int64, error)
MintId returns a fresh candidate from the Session-global numeric ID namespace.
func (*SqliteStorage) ScanConversations ¶
func (storage *SqliteStorage) ScanConversations( _ context.Context, query durable.ConversationQuery, limit int, cursor durable.Cursor, ) (durable.Page[durable.ConversationRecord, durable.Cursor], error)
ScanConversations scans conversations in ascending ID order.
func (*SqliteStorage) ScanDocuments ¶
func (storage *SqliteStorage) ScanDocuments( _ context.Context, query durable.DocumentQuery, limit int, cursor durable.Cursor, ) (durable.Page[durable.DocumentRecord, durable.Cursor], error)
ScanDocuments scans incarnations alive in one exact scope at the selected point.
func (*SqliteStorage) ScanEntries ¶
func (storage *SqliteStorage) ScanEntries( _ context.Context, query durable.EntryQuery, limit int, cursor durable.Cursor, ) (durable.Page[durable.EntryRecord, durable.Cursor], error)
ScanEntries scans the inclusive visible range newest-first, returning at most limit entries.
func (*SqliteStorage) ScanSubmissions ¶
func (storage *SqliteStorage) ScanSubmissions( _ context.Context, query durable.SubmissionQuery, limit int, cursor durable.Cursor, ) (durable.Page[durable.SubmissionRecord, durable.Cursor], error)
ScanSubmissions scans submissions matching every supplied filter in ascending ID order.
func (*SqliteStorage) ScanTasks ¶
func (storage *SqliteStorage) ScanTasks( _ context.Context, query durable.TaskQuery, limit int, cursor durable.Cursor, ) (durable.Page[storedTask, durable.Cursor], error)
ScanTasks scans task records matching every supplied filter.
func (*SqliteStorage) Submission ¶
func (storage *SqliteStorage) Submission( _ context.Context, id durable.SubmissionId, ) (*durable.SubmissionRecord, error)
Submission looks up the latest complete record for one admitted submission.
func (*SqliteStorage) SubmissionByRequest ¶
func (storage *SqliteStorage) SubmissionByRequest( _ context.Context, conversationId durable.ConversationId, requestId string, ) (*durable.SubmissionRecord, error)
SubmissionByRequest finds a submission by its conversation-scoped host deduplication key.
func (*SqliteStorage) VisibleEntry ¶
func (storage *SqliteStorage) VisibleEntry( _ context.Context, conversationId durable.ConversationId, id durable.EntryId, ) (*durable.EntryAt, error)
VisibleEntry looks up one entry only when it is visible through the requested conversation's ancestry.
type SqliteValue ¶
type SqliteValue = any
SqliteValue is a value supported by the portable SQLite storage core: nil, int64 (or any Go integer), float64, string, or []byte.