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) DeleteVersion(ctx context.Context, docName string, versionID int64) 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) GetVersionState(ctx context.Context, docName string, versionID int64) ([]byte, error)
- func (s *Store) ListDocuments(ctx context.Context) ([]string, error)
- func (s *Store) ListVersions(ctx context.Context, docName string) ([]persist.VersionInfo, error)
- func (s *Store) RestoreVersion(ctx context.Context, docName string, versionID int64) error
- func (s *Store) SaveVersion(ctx context.Context, docName, label string, state []byte) (int64, 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) DeleteVersion ¶ added in v1.1.0
DeleteVersion removes one version. Idempotent on unknown versions.
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 write transaction opened with BEGIN IMMEDIATE, so a concurrent StoreUpdate either commits before Flush takes the write lock (and is folded into the snapshot) or blocks on that lock until Flush commits and then appends to the now-shorter log. A torn intermediate state is never observable.
The transaction is IMMEDIATE, not the default deferred, on purpose. A deferred transaction would take only a read snapshot for the SELECT and then try to upgrade to a writer at the DELETE; on a WAL database a StoreUpdate committing in that gap invalidates the snapshot and the upgrade fails at once with SQLITE_BUSY_SNAPSHOT, which the busy_timeout does NOT service, so Flush would fail a large fraction of the time on a live document. Taking the write lock up front routes contention through busy_timeout instead (a concurrent writer waits, bounded, rather than failing the flush), which is what makes Flush reliable on a hot doc.
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. Under extreme, sustained write contention BEGIN IMMEDIATE may itself exceed busy_timeout and return a transient busy error; the log is untouched and the caller may retry.
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) GetVersionState ¶ added in v1.1.0
func (s *Store) GetVersionState(ctx context.Context, docName string, versionID int64) ([]byte, error)
GetVersionState returns the state blob of one version.
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.
func (*Store) ListVersions ¶ added in v1.1.0
ListVersions returns the metadata of every version of docName, oldest first. (nil, nil) when the document has no versions.
func (*Store) RestoreVersion ¶ added in v1.1.0
RestoreVersion replaces docName's live update log with the version's state blob, inside one SQLite transaction: concurrent readers and writers see either the old log or the restored single-blob log, never a torn intermediate state.
The restored log starts a new history for connected clients: the document's state vector regresses to the version's, so live sync sessions must resynchronize from scratch. Intended for administrative restore, not for use mid-session.
Source Files