Documentation
¶
Overview ¶
Package sqlite implements the persistence port interfaces using an embedded SQLite database via zombiezen.com/go/sqlite (pure Go, no CGO). It provides database discovery (walking up from cwd to find .np/), schema management, and all CRUD operations with transactional guarantees.
The Store uses a connection pool (sqlitex.Pool) with per-connection pragma setup for WAL mode, foreign keys, and a busy timeout. Write transactions use BEGIN IMMEDIATE so that lock contention is detected — and retried via the busy handler — at BEGIN rather than mid-transaction.
Index ¶
- func DiscoverDatabase(startDir string) (string, error)
- func InitDatabaseDir(baseDir string) (string, error)
- func LookupDatabase(dir string) (string, error)
- type Store
- func (s *Store) CheckSchemaVersion(ctx context.Context) error
- func (s *Store) Close() error
- func (s *Store) MigrateV1ToV2(ctx context.Context) (driven.MigrationResult, error)
- func (s *Store) Vacuum(ctx context.Context) error
- func (s *Store) WithReadTransaction(ctx context.Context, fn func(uow driven.UnitOfWork) error) (err error)
- func (s *Store) WithTransaction(ctx context.Context, fn func(uow driven.UnitOfWork) error) (err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiscoverDatabase ¶
DiscoverDatabase walks up from startDir looking for a .np/ directory. Returns the full path to the database file, or an error if not found.
Permission and sandbox errors are silently ignored per §3.3 — if a directory cannot be read, it is skipped.
func InitDatabaseDir ¶
InitDatabaseDir creates the .np/ directory and returns the database path.
func LookupDatabase ¶
LookupDatabase checks a single directory for a .np/ workspace without walking up to parent directories. Returns the full path to the database file, or an error if the directory does not contain an np workspace. Use this when the caller has specified an explicit workspace directory.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store provides SQLite-backed persistence for the nitpicking domain.
func Create ¶
Create creates a new SQLite database at dbPath and applies the schema. Intended to be called once during database initialisation ("np init"). Subsequent access should use Open, which skips DDL.
func Open ¶
Open opens an existing SQLite database at dbPath. It does not apply schema DDL — the database must already have been created with Create.
func (*Store) CheckSchemaVersion ¶ added in v0.2.0
CheckSchemaVersion opens a read transaction, fetches the schema version, and returns domain.ErrSchemaMigrationRequired (wrapped in a DatabaseError) when the version is below 2. Callers — typically root-command startup hooks — use this to gate all database-touching commands on a migrated database.
func (*Store) MigrateV1ToV2 ¶ added in v0.2.0
MigrateV1ToV2 upgrades a v1 database to v2 schema in a single atomic transaction, satisfying the driven.Migrator interface. It is safe to call on a v2 database — CheckSchemaVersion should be called first so that callers can report "up to date" without executing the migration body.
The migration performs three steps within one IMMEDIATE transaction:
- Updates every issue with state="claimed" to state="open", so that the primary state column contains only lifecycle states. The active claims are already stored in the claims table and remain untouched.
- Deletes history rows whose event_type is "claimed" or "released" — these event types were removed in v2; the claims table replaces them.
- Sets schema_version=2 in the metadata table via SetSchemaVersion, marking the migration as complete.
If any step fails the transaction is rolled back and the database is unchanged. Returns a driven.MigrationResult with the number of rows affected by each step.
func (*Store) Vacuum ¶
Vacuum reclaims disk space and defragments the database file. Must be called outside any transaction — takes a connection from the pool, runs VACUUM, and returns it.
func (*Store) WithReadTransaction ¶
func (s *Store) WithReadTransaction(ctx context.Context, fn func(uow driven.UnitOfWork) error) (err error)
WithReadTransaction executes fn within a deferred (read-only) transaction.
func (*Store) WithTransaction ¶
func (s *Store) WithTransaction(ctx context.Context, fn func(uow driven.UnitOfWork) error) (err error)
WithTransaction executes fn within an IMMEDIATE transaction. IMMEDIATE acquires a write lock at BEGIN so that busy-handler retries happen at a point where no deadlock is possible.
Source Files