db

Documentation

Overview

Package db opens the project SQLite file and applies the schema.

Index

• Constants
• Variables
• func DefaultPath(dir string) string
• func IsBusy(err error) bool
• func Open(path string) (*sql.DB, error)
• func OpenWith(path string, opts Options) (*sql.DB, error)
• func Resolve(start string) (string, error)
• func RetryBusy(fn func() error) error
• type Options

Constants

const DBDirName = ".stint"

DBDirName is the per-project directory that holds the SQLite file.

const DBFileName = "stint.db"

DBFileName is the SQLite database filename within DBDirName.

const SchemaVersion = 11

SchemaVersion is the version this build expects. Migrations bring older DBs up to this version on open.

Variables

var ErrBusy = errors.New("database is busy after retries")

ErrBusy is the sentinel returned by RetryBusy when the database stayed locked across every retry. The CLI envelope classifier maps it to code:"busy" so orchestrators can pick a retry-with-backoff loop without parsing string fragments.

Why a sentinel rather than letting the raw `database is locked (5) (SQLITE_BUSY)` bubble up: that string varies by driver version and gets classified as code:"internal" today, which is wrong — busy is an expected, recoverable contention signal, not a stint bug.

var ErrNoProject = fmt.Errorf("no stint project found (run `stint init`)")

ErrNoProject indicates that no .stint/stint.db was found walking upward.

Functions

func DefaultPath

func DefaultPath(dir string) string

DefaultPath returns the path to the DB file inside dir.

func IsBusy

func IsBusy(err error) bool

IsBusy reports whether err is a SQLite busy / lock contention error. The modernc.org/sqlite driver renders these as text containing either "SQLITE_BUSY" or "database is locked" depending on context; we match on both so a future driver bump that only emits one form still triggers the retry path.

func Open

func Open(path string) (*sql.DB, error)

Open opens (and if absent, creates) the SQLite file at path and applies the schema + any pending migrations. The caller owns Close().

func OpenWith

func OpenWith(path string, opts Options) (*sql.DB, error)

OpenWith is Open with options. Splitting keeps the common path one-line.

func Resolve

func Resolve(start string) (string, error)

Resolve walks up from start looking for a .stint/stint.db file; returns its absolute path. If the walk-up finds nothing AND start is inside a linked git worktree, it falls back to the main checkout's .stint/stint.db — a linked worktree checks out .stint/ (docs, scaffold.lock) but never the gitignored stint.db, so the project DB lives only in the main checkout. If neither the walk-up nor the fallback finds a DB, returns ErrNoProject.

func RetryBusy

func RetryBusy(fn func() error) error

RetryBusy invokes fn up to busyRetryMax+1 times, sleeping a jittered backoff between attempts whenever fn returns a SQLite busy error. On the final still-busy attempt it returns ErrBusy wrapping the last raw error so callers can errors.Is(err, ErrBusy) without losing the underlying driver message for diagnostics.

Use this around store mutations that contend in practice: ClaimTask and NextTaskForAgent are the hot pair, since `stint task next` fanned out to N parallel agents will race on the same row. Other mutations still benefit from busy_timeout(5s) at the connection level.

Types

type Options

type Options struct {
	// Readonly opens the DB with `query_only=1`. Mutations attempted via the
	// connection will fail at the SQLite layer (`attempt to write a readonly
	// database`). The file must already exist; schema apply + migrations are
	// skipped because they would themselves attempt writes.
	Readonly bool
}

Options tunes Open. Zero value = the historical Open behavior.