sqlite

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
const DefaultWorkingSetBytes = 64 << 20

DefaultWorkingSetBytes is the default bound on the decoded entries a SqliteStorage retains.

Variables

View Source
var CurrentSqliteSchemaVersion = lastVersion(SqliteMigrations)

CurrentSqliteSchemaVersion is the version of the last migration in SqliteMigrations.

View Source
var DefaultSqliteSchema = mustDefaultSchema()

DefaultSqliteSchema is the schema without a prefix.

SqliteMigrations is the immutable, ordered schema history of the unprefixed schema. Append new migrations after the initial schema ships.

View Source
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) (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

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

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) Task

func (storage *SqliteStorage) Task(_ context.Context, id durable.TaskId) (*storedTask, error)

Task looks up the latest complete record for one task.

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.

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.

Jump to

Keyboard shortcuts

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