Documentation
¶
Overview ¶
Package sqlite is the default on-disk agent.Store: a single-file, zero-cgo SQLite journal (via modernc.org/sqlite). An agent run journaled here survives a process crash and resumes without re-running completed steps. No cluster, no daemon: one binary and one file.
Store implements agent.Store, agent.Lister (so agent.Recover finds the runs to re-drive after a restart) and agent.Leaser (so processes sharing the file drive each run one at a time). Open opens three connection pools on the file: a writer of one connection for every Insert and Get, readers for Load and Runs, and a lease connection of its own, whose statements use a short busy timeout so a writer holding the file's lock never delays a lease renewal past its cutoff.
The tables are named with a prefix, "bide_" by default (see WithTablePrefix): bide_steps holds the journal, bide_leases the leases, and bide_schema_version the schema version. Open refuses a file whose schema version is newer than this version knows. The file must be on a local disk: SQLite's locking does not work over NFS. A forward jump of the system clock expires leases early, which the journal's attempt claims keep safe.
Index ¶
- type Option
- type Store
- func (s *Store) AcquireLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
- func (s *Store) Close() error
- func (s *Store) Get(ctx context.Context, runID, name string) (agent.Entry, bool, error)
- func (s *Store) Insert(ctx context.Context, runID, name string, data []byte) (agent.Entry, bool, error)
- func (s *Store) Load(ctx context.Context, runID string, after int64) iter.Seq2[agent.Entry, error]
- func (s *Store) ReapLeases(ctx context.Context, ended []string) (int, error)
- func (s *Store) ReleaseLease(ctx context.Context, runID, holder string) error
- func (s *Store) RenewLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
- func (s *Store) Runs(ctx context.Context, f agent.RunFilter) iter.Seq2[string, error]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶ added in v0.9.0
type Option interface {
// contains filtered or unexported methods
}
Option configures Open and New.
func WithTablePrefix ¶ added in v0.9.0
WithTablePrefix names the tables with prefix instead of "bide_": prefix+"steps", prefix+"leases" and prefix+"schema_version". It must be an SQL identifier (letters, digits and underscores, not starting with a digit), or Open and New return an ErrConfig error.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a SQLite-backed agent.Store.
func New ¶ added in v0.9.0
New returns a Store over db, which the caller opened and closes. db must be in WAL mode and allow at least two open connections (a Load's page and a write inside its loop may each need one); New returns an ErrConfig error otherwise. Its connections should set a busy timeout of several seconds (modernc.org/sqlite: _pragma=busy_timeout(30000) in the DSN), since a write that gives up on another process's lock fails a step whose side effect may have run. All three roles share db, so a lease statement can wait behind the caller's other work; Open avoids that.
func Open ¶
Open opens (creating if needed) a SQLite journal at path, in WAL mode, with its three connection pools. ":memory:" opens an ephemeral in-memory store for tests, on one connection shared by all three roles (an in-memory database lives on one connection).
func OpenReadOnly ¶ added in v0.13.0
OpenReadOnly opens the SQLite journal at path for reading only. The file is opened read-only (mode=ro and query_only) on one pool of up to four connections; nothing is created, migrated or checkpointed. Get, Load and Runs (agent.Lister) read as they do on a Store from Open. Every write fails: Insert with an error wrapping agent.ErrStorage, and the agent.Leaser methods with an error. opts are Open's (WithTablePrefix names the tables to read).
It refuses ":memory:" (ErrConfig), a missing file (which it does not create), a file with no journal tables, and one whose schema version is newer than this version's (ErrConfig). A journal another process is writing in WAL mode can be read while it runs; each read sees the journal as of that read. Close closes the pool. It is for tools that inspect a journal, such as bide-view, never for driving a run.
func (*Store) AcquireLease ¶ added in v0.9.0
func (s *Store) AcquireLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
AcquireLease implements agent.Leaser with one upsert: it grants the lease when the run is unleased, already held by holder (a renewal), or the current lease has expired.
func (*Store) Close ¶
Close closes the connection pools Open opened. A Store made with New leaves its db open.
func (*Store) Get ¶ added in v0.9.0
Get implements agent.Store. It reads on the writer's connection: the journal reads a step just before it writes one, and a point read on another connection of the same file costs about as much again as the write, which the reader pool is for bulk reads (Load, Runs) to avoid.
func (*Store) Insert ¶ added in v0.9.0
func (s *Store) Insert(ctx context.Context, runID, name string, data []byte) (agent.Entry, bool, error)
Insert implements agent.Store. An entry's Seq is its row id, which SQLite assigns as one more than the table's highest when the row is inserted, under the database's single write lock: so it increases in commit order, within a run and across the table. The entry it returns for a new row holds data itself (SQLite copied it).
func (*Store) Load ¶ added in v0.9.0
Load implements agent.Store. It reads pageSize entries per query and yields them with no connection held, so the caller may write to the store inside its loop.
func (*Store) ReapLeases ¶ added in v0.10.0
ReapLeases implements agent.Leaser with one DELETE, which checks the expiry in the same statement, so a lease taken or renewed meanwhile is kept. The lapsed leases it deletes are those no recovery pass takes over: a finished run's, one on a run the steps table does not hold, and one on a run whose ID contains '>' (a session's or a sub-agent's run).
func (*Store) ReleaseLease ¶ added in v0.9.0
ReleaseLease implements agent.Leaser: it deletes runID's lease if holder holds it.
Source Files