sqlite

Documentation

Overview

Package sqlite provides a SQLite-backed glue.Store with FTS5 over message text. Implementation uses modernc.org/sqlite — pure Go, no CGo, cross-compiles freely.

One DB file per Store instance; multiple sessions share the file. The file is opened in WAL mode for concurrent reads.

stores/file remains the simple option. Reach for stores/sqlite when you need cross-session search (it implements the optional Searcher capability behind Agent.SearchSessions / Session.Search) or when many sessions live in one process.

Design: docs/adr/0007-memory-layer.md §2.

Index

• Constants
• type Options
• type Store
  • func Open(opts Options) (*Store, error)
  • func (s *Store) Close() error
  • func (s *Store) DB() *sql.DB
  • func (s *Store) Delete(ctx context.Context, id string) error
  • func (s *Store) ListSessions(ctx context.Context, opts glue.ListSessionsOptions) ([]glue.SessionSummary, error)
  • func (s *Store) Load(ctx context.Context, id string) (glue.SessionState, bool, error)
  • func (s *Store) Save(ctx context.Context, id string, state glue.SessionState) error
  • func (s *Store) Search(ctx context.Context, query string, opts glue.SearchOptions) ([]glue.SearchHit, error)

Constants

const SchemaVersion = 1

SchemaVersion is the on-disk schema version this build writes and expects to read. Exposed for tests and operators.

Types

type Options

type Options struct {
	// Path is the SQLite file path. ":memory:" is accepted and useful
	// in tests. Required.
	Path string

	// Timeout sets the SQLite busy_timeout. Default 5s.
	Timeout time.Duration
}

Options configures a Store.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store implements glue.Store against a SQLite file with FTS5 over message text.

func Open

func Open(opts Options) (*Store, error)

Open creates or opens a SQLite store at opts.Path, applies WAL + related PRAGMAs, and runs the idempotent schema. It is safe to call Open multiple times against the same path from different processes; WAL mode permits concurrent reads with a single writer.

func (*Store) Close

func (s *Store) Close() error

Close releases the database handle.

func (*Store) DB

func (s *Store) DB() *sql.DB

DB returns the underlying *sql.DB for tests and future Searcher implementations that need direct query access. Public consumers should treat the returned handle as read-only outside of the Store's Save / Load / Delete API.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, id string) error

Delete implements glue.Store. Missing sessions are a no-op success. Foreign-key cascade removes the message rows; the FTS triggers remove their index rows.

func (*Store) ListSessions

func (s *Store) ListSessions(ctx context.Context, opts glue.ListSessionsOptions) ([]glue.SessionSummary, error)

ListSessions implements glue.SessionLister.

func (*Store) Load

func (s *Store) Load(ctx context.Context, id string) (glue.SessionState, bool, error)

Load implements glue.Store.

func (*Store) Save

func (s *Store) Save(ctx context.Context, id string, state glue.SessionState) error

Save implements glue.Store. Atomic: a single BEGIN IMMEDIATE transaction upserts the session row, deletes any prior messages for the id, and re-inserts the supplied messages in order.

func (*Store) Search

func (s *Store) Search(ctx context.Context, query string, opts glue.SearchOptions) ([]glue.SearchHit, error)

Search implements glue.Searcher against the FTS5 index. Hits are ordered by BM25 ascending (lower is better, matching FTS5's convention). See docs/adr/0007-memory-layer.md §3.

query is forwarded straight to messages_fts MATCH; FTS5's standard syntax applies (bare words, "quoted phrases", AND / OR / NOT).