Documentation
¶
Overview ¶
Package sqlite is the portable SQLite storage core of pi-durable: the durable schema, its migrations, and SqliteStorage. The database facade and the migration runner are Chord's (chord/sqlite); durable/storage/sqlite/node and durable/storage/sqlite/cloudflare open storage on Chord's drivers.
Index ¶
- Constants
- Variables
- func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration) error
- func ApplySqliteMigrationsForSchema(database SqliteDatabase, schema SqliteSchema, migrations []SqliteMigration) error
- type SqliteDatabase
- type SqliteExecutor
- type SqliteIndexes
- type SqliteMigration
- type SqliteRow
- type SqliteSchema
- type SqliteStorage
- func (storage *SqliteStorage) Close(_ context.Context) error
- func (storage *SqliteStorage) Commit(_ context.Context, batch []durable.StorageWrite, adopt func(durable.Seq)) (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)
- func (storage *SqliteStorage) VisibleEntryRange(_ context.Context, query durable.EntryQuery) ([]durable.EntryRecord, error)
- type SqliteStorageOptions
- type SqliteTables
- type SqliteValue
- type TextReader
Constants ¶
const DefaultWorkingSetBytes = 64 << 20
DefaultWorkingSetBytes is the default bound on the decoded entries a SqliteStorage retains.
Variables ¶
var CurrentSqliteSchemaVersion = lastVersion(SqliteMigrations)
CurrentSqliteSchemaVersion is the version of the last migration in SqliteMigrations.
var DefaultSqliteSchema = mustDefaultSchema()
DefaultSqliteSchema is the schema without a prefix.
var SqliteMigrations = CreateSqliteMigrations(DefaultSqliteSchema)
SqliteMigrations is the immutable, ordered schema history of the unprefixed schema. Append new migrations after the initial schema ships.
var ValidateSqliteSchemaPrefix = chordsqlite.ValidateSqliteSchemaPrefix
ValidateSqliteSchemaPrefix is Chord's prefix check, re-exported as Pi's durable schema entry point re-exports it.
Functions ¶
func ApplySqliteMigrations ¶
func ApplySqliteMigrations(database SqliteDatabase, migrations []SqliteMigration) error
ApplySqliteMigrations applies all pending schema migrations of the unprefixed schema atomically. A nil migrations slice selects SqliteMigrations; a non-nil empty slice applies none.
func ApplySqliteMigrationsForSchema ¶
func ApplySqliteMigrationsForSchema(database SqliteDatabase, schema SqliteSchema, migrations []SqliteMigration) error
ApplySqliteMigrationsForSchema applies migrations rendered for a particular schema. A nil migrations slice selects CreateSqliteMigrations(schema); a non-nil empty slice applies none.
Types ¶
type SqliteDatabase ¶
type SqliteDatabase = chordsqlite.SqliteDatabase
The Chord facade's names, re-exported as Pi's durable database entry point re-exports them.
type SqliteExecutor ¶
type SqliteExecutor = chordsqlite.SqliteExecutor
The Chord facade's names, re-exported as Pi's durable database entry point re-exports them.
type SqliteIndexes ¶
type SqliteIndexes struct {
ConversationsByOwnerConversation string
ConversationsByOwnerTask string
EntriesByConversation string
EntryHeadsByConversation string
TasksByStatus string
TasksByConversation string
TasksByKind string
TasksByAbortRequested string
TasksByBackground string
SubmissionsByRequest string
SubmissionsByConversation string
SubmissionsByStatus string
DocumentsByAddress string
DocumentsByScope string
DocumentsByScopeKind string
DocumentRevisionsByKind string
}
SqliteIndexes are the index names of the durable schema, with the same stability rule as SqliteTables (schema.ts INDEX_NAMES).
type SqliteMigration ¶
type SqliteMigration = chordsqlite.SqliteMigration
SqliteMigration is Chord's migration type, re-exported as Pi's durable migrations entry point re-exports it.
func CreateSqliteMigrations ¶
func CreateSqliteMigrations(schema SqliteSchema) []SqliteMigration
CreateSqliteMigrations builds the immutable, ordered schema history for a set of SQLite identifiers (createSqliteMigrations).
type SqliteRow ¶
type SqliteRow = chordsqlite.SqliteRow
The Chord facade's names, re-exported as Pi's durable database entry point re-exports them.
type SqliteSchema ¶
type SqliteSchema struct {
Tables SqliteTables
Indexes SqliteIndexes
}
SqliteSchema is the identifiers every migration and storage query uses.
func CreateSqliteSchema ¶
func CreateSqliteSchema(prefix *string) (SqliteSchema, error)
CreateSqliteSchema builds the identifiers of every migration and storage query. A nil prefix leaves the names as they are; a present prefix, even an empty one, must pass ValidateSqliteSchemaPrefix.
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, options ...SqliteStorageOptions) (*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, adopt func(durable.Seq)) (durable.Seq, error)
Commit atomically persists one batch, adopts it, 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 by ID in query.Order, ascending by default.
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 in query.Order (descending by default), 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 by ID in query.Order, ascending by default.
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 by ID in query.Order, ascending by default.
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.
func (*SqliteStorage) VisibleEntryRange ¶
func (storage *SqliteStorage) VisibleEntryRange(_ context.Context, query durable.EntryQuery) ([]durable.EntryRecord, error)
VisibleEntryRange returns the visible entries within query's bounds, oldest first, from the working set. The result is shared with the storage and read-only.
type SqliteStorageOptions ¶
type SqliteStorageOptions struct {
// Prefix namespaces every table and index of the durable schema, for a database shared with other tables. It must
// be a SQLite identifier and must not use SQLite's reserved `sqlite_` prefix. Existing data is not migrated when it
// changes. Nil leaves the names unprefixed; a present empty prefix is invalid.
Prefix *string
// WorkingSetBytes bounds the decoded entries the storage retains for context reads: zero selects
// DefaultWorkingSetBytes and a negative value retains nothing.
WorkingSetBytes int64
}
SqliteStorageOptions configures a SqliteStorage (Pi's SqliteStorageOptions, which has Prefix only; WorkingSetBytes is additive, D104).
type SqliteTables ¶
type SqliteTables struct {
DurableSchema string
DurableMetadata string
RecordIds string
Conversations string
Entries string
Tasks string
Submissions string
Documents string
DocumentRevisions string
}
SqliteTables are the table names of the durable schema. The values never change or disappear; a rename adds a new entry so historical migrations keep rendering their original object names (schema.ts TABLE_NAMES).
type SqliteValue ¶
type SqliteValue = chordsqlite.SqliteValue
The Chord facade's names, re-exported as Pi's durable database entry point re-exports them.
type TextReader ¶
type TextReader = chordsqlite.TextReader
The Chord facade's names, re-exported as Pi's durable database entry point re-exports them.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cloudflare opens durable storage on the SQLite storage of a Cloudflare Durable Object.
|
Package cloudflare opens durable storage on the SQLite storage of a Cloudflare Durable Object. |
|
Package node opens durable storage on a native SQLite connection.
|
Package node opens durable storage on a native SQLite connection. |