Documentation
¶
Overview ¶
Package sqlite is the reference persist.Store implementation backed by modernc.org/sqlite. modernc.org/sqlite is a pure-Go translation of SQLite — no CGO — so binaries built against this package preserve the project's gomobile-friendly stance (see DESIGN.md).
Use cases:
Production single-process storage where SQLite's single-writer model is acceptable. Read concurrency is unlimited; writes serialize at the file lock.
Tests, via Open(":memory:"). Each in-memory database is isolated to the *sql.DB connection pool that owns it; tests do not interfere even when run in parallel.
Reference for porting a different backing engine. The schema, write path, and Flush transaction here are the canonical shape; deviations should be justified.
The schema is the smallest viable form: an append-only log of (doc_name, opaque blob) tuples ordered by autoincrement primary key. No additional indexes beyond the doc_name lookup; no separate meta table; no clientID stored alongside. The log alone suffices because all wire-format invariants (clock-per-client, state vector, delete set) live inside the V1 update blobs themselves.
Index ¶
- type Store
- func (s *Store) ClearDocument(ctx context.Context, docName string) error
- func (s *Store) Close() error
- func (s *Store) DocumentExists(ctx context.Context, docName string) (bool, error)
- func (s *Store) Flush(ctx context.Context, docName string) error
- func (s *Store) GetUpdates(ctx context.Context, docName string) ([][]byte, error)
- func (s *Store) ListDocuments(ctx context.Context) ([]string, error)
- func (s *Store) StoreUpdate(ctx context.Context, docName string, update []byte) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements persist.Store on top of a SQLite database.
Concurrency: safe for concurrent use from multiple goroutines. modernc.org/sqlite + database/sql serialize writes at the file lock; reads are unbounded. Callers do not need to synchronize.
func Open ¶
Open opens (or creates) a SQLite database at path and returns a ready-to-use Store. The schema is created on first open and is a no-op on subsequent opens of the same database.
Use ":memory:" for an ephemeral in-memory database. The Store clamps the connection pool to a single connection in that mode because modernc.org/sqlite (like reference SQLite) gives each connection its own private in-memory database. Without the clamp, a write on one connection would land in a different database than a read on another connection — every test would mysteriously fail with "no such table".
Concurrency note: although Store is safe for concurrent use, opening the SAME on-disk path twice from the same process creates two independent *sql.DB pools. SQLite's file-lock serializes their writes correctly, but they will not see each other's uncommitted transactions. Prefer a single Store per database file per process.
func (*Store) ClearDocument ¶
ClearDocument removes every update for docName. Idempotent.
func (*Store) Close ¶
Close releases the underlying *sql.DB. Safe to call more than once; subsequent calls return nil without touching the database.
func (*Store) DocumentExists ¶
DocumentExists reports whether docName has any stored updates.
func (*Store) Flush ¶
Flush replaces all updates for docName with a single merged snapshot. The read-merge-replace runs inside one SQLite transaction so concurrent StoreUpdate calls either land before the snapshot is taken (and get folded in) or after the replace commits (and append to the now-shorter log). A torn intermediate state is not observable.
Idempotent: no-op for documents with zero or one stored updates. Returns the error from persist.MergeUpdates without touching the database when the snapshot cannot be computed; the original log stays canonical.
func (*Store) GetUpdates ¶
GetUpdates returns every update blob stored for docName, in insertion order. Returns (nil, nil) — empty slice, no error — for an unknown document.
func (*Store) ListDocuments ¶
ListDocuments returns the names of every document with at least one stored update. Order is by doc_name ascending — not part of the persist.Store contract, but deterministic ordering keeps tests stable.
Source Files