Documentation
¶
Overview ¶
Package sqlite implements Sigil storage on a local SQLite database. It requires CGO and the bundled mattn/go-sqlite3 driver. Open takes a path, owns the pool and claims the whole file. New borrows a pool the host opened with DSN on the database its own tables already live in, and then claims only the reserved "auth_" prefix, the relations plugins register and the indexes and triggers attached to those; everything else stays the host's. Apply explicitly migrates and Check verifies schema history and configuration. Security operations use BEGIN IMMEDIATE and serialize writers across processes. ApplyPlugins serves adapter contract version 1: plugins that declare explicit SQLite migrations install here, and plugins that declare none are rejected rather than falling back to PostgreSQL SQL. See docs/sqlite-adapter.md for concurrency and deployment restrictions.
Index ¶
- Variables
- func DSN(path string) (string, error)
- type Migration
- type PluginTx
- type Store
- func (s *Store) Apply(ctx context.Context) error
- func (s *Store) ApplyPlan(ctx context.Context, registry plugin.Registry, plan storage.MigrationPlan) error
- func (s *Store) ApplyPlugins(ctx context.Context, registry plugin.Registry) error
- func (s *Store) AuditEvents(ctx context.Context, q storage.AuditQuery) ([]storage.AuditEvent, error)
- func (*Store) Capabilities() storage.Capabilities
- func (s *Store) Check(ctx context.Context) error
- func (s *Store) CheckPlugins(ctx context.Context, schemas []storage.PluginSchema) error
- func (s *Store) ClaimDelivery(ctx context.Context) (d storage.Delivery, err error)
- func (s *Store) CleanupDeliveries(ctx context.Context, limit int) (n int64, err error)
- func (s *Store) Close() error
- func (s *Store) ConsumeAbuse(ctx context.Context, budgets []storage.AbuseBudget) (retry time.Duration, err error)
- func (s *Store) FinishDelivery(ctx context.Context, id string, attempt int, delivered bool) error
- func (s *Store) LiveDeliveries(ctx context.Context, afterID string, limit int) ([]storage.Delivery, error)
- func (s *Store) Plan(ctx context.Context, registry plugin.Registry) (storage.MigrationPlan, error)
- func (s *Store) PruneAuditEvents(ctx context.Context, before time.Time, limit int) (n int64, err error)
- func (s *Store) PruneExpired(ctx context.Context, before time.Time, limit int) (out storage.Pruned, err error)
- func (s *Store) RecordAuditEvent(ctx context.Context, e storage.AuditEvent) error
- func (s *Store) ReplaceDeliveryPayload(ctx context.Context, id string, expected, replacement storage.Material) error
- func (s *Store) WithinTx(ctx context.Context, fn func(storage.Tx) error) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrPending = errors.New("sqlite: core migrations pending") ErrSchema = errors.New("sqlite: incompatible or altered core schema") )
var ErrPluginPending = errors.New("sqlite: plugin migrations pending")
var ErrPluginSchema = errors.New("sqlite: incompatible plugin history, ownership or schema")
Functions ¶
func DSN ¶
DSN renders the only driver configuration this adapter accepts, so a host opening its own pool for New does not have to restate the options by hand. The zero busy timeout is deliberate: the adapter owns context-aware lock acquisition, and a driver-side wait would ignore context cancellation.
Types ¶
type Migration ¶
func Migrations ¶
func Migrations() []Migration
Migrations returns the embedded core migrations in order. Each history row records a version, name and the hex SHA-256 of that SQL.
type PluginTx ¶
type PluginTx struct {
// contains filtered or unexported fields
}
PluginTx shares the core transaction and its failure state. Binding acquires the database writer lock before any plugin reads, including anonymous flows.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store reaches the database through a pool it either owns or borrows. All connections enforce foreign keys, WAL and FULL synchronous durability. Apply explicitly installs migrations; Check never changes the schema.
Open takes a filesystem path, never a SQLite DSN, and owns both the pool and the whole file: any object it does not recognise fails the schema check. New borrows a pool on a database the host also uses for its own tables, and then claims only the reserved prefix and the names plugins registered.
func New ¶
New borrows a pool the host already opened on its own database, so Sigil needs no second file. The host keeps ownership: Close leaves the pool open and pool sizing stays the host's decision. Open that pool with DSN; Check rejects a pool configured any other way rather than running without the guarantees the adapter depends on. Sigil claims the reserved "auth_" prefix and the relation names its plugins declare; every other object in the database stays the host's, unread and unreported. SQLite still admits one writer per database, so a host write transaction and a Sigil write transaction on different connections block each other: never call a Sigil write from inside an open host write transaction.
func (*Store) Apply ¶
Apply atomically installs the pending embedded core migrations and their checksum history. It is idempotent, serializes across processes and refuses drift/future versions.
func (*Store) ApplyPlan ¶
func (s *Store) ApplyPlan(ctx context.Context, registry plugin.Registry, plan storage.MigrationPlan) error
ApplyPlan applies a reviewed plan, refusing with storage.ErrPlanChanged and changing nothing unless the plan was made by these declarations and every owner is still at its recorded version. Each comparison happens inside the immediate transaction that applies. Core and plugins commit separately, as Apply and ApplyPlugins do.
func (*Store) ApplyPlugins ¶
ApplyPlugins explicitly applies the compiled registry in dependency order. Core must be installed first. All enabled upgrades commit atomically.
func (*Store) AuditEvents ¶
func (s *Store) AuditEvents(ctx context.Context, q storage.AuditQuery) ([]storage.AuditEvent, error)
func (*Store) Capabilities ¶
func (*Store) Capabilities() storage.Capabilities
func (*Store) Check ¶
Check verifies configuration, exact migration history and the installed DDL. A store from Open requires a dedicated file and fails closed on any unowned table. A store from New inspects only the relations Sigil owns, and leaves the host's own tables in the same database unread.
func (*Store) CheckPlugins ¶
func (*Store) ClaimDelivery ¶
func (*Store) CleanupDeliveries ¶
func (*Store) Close ¶
Close releases a pool this adapter opened. A borrowed pool is the host's to close, once its own work and Sigil's have both stopped.
func (*Store) ConsumeAbuse ¶
func (*Store) FinishDelivery ¶
func (*Store) LiveDeliveries ¶
func (*Store) Plan ¶
Plan returns the inspectable plan of what Apply and then ApplyPlugins with this registry would execute: the core schema if it is not installed, then each enabled plugin's pending versions in dependency order, with the SQLite bodies and the checksums the ledger records. It is read-only and validates what the applies validate. Before core is installed no plugin can be, so every plugin starts at version zero once its relation names are shown to be free. Over an older core, the plan moves core forward before any plugin.
Source Files