Documentation
¶
Overview ¶
Package locks diagnoses SQLite locking and writer-starvation issues. It inspects PRAGMA settings for local databases and provides provider-specific guidance for D1 and Turso where PRAGMAs are not directly accessible.
Index ¶
Constants ¶
const ( SeverityOK = "ok" SeverityWarning = "warning" SeverityCritical = "critical" )
Severity levels for lock findings.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Finding ¶
type Finding struct {
Severity string // "ok" | "warning" | "critical"
Rule string // machine-readable rule ID
Summary string // one-line description of the problem
Detail string // explanation of why this matters
Fix string // exact PRAGMA/config to apply (empty if n/a)
}
Finding is one diagnosed locking issue with a concrete prescription.
type Holder ¶
type Holder struct {
PID int `json:"pid"`
Command string `json:"command"`
Access string `json:"access"` // "r" | "w" | "rw" | "u" (unknown)
}
Holder is a process holding the database file open, as reported by lsof.
type LiveProbe ¶
type LiveProbe struct {
Source string `json:"source"`
Time time.Time `json:"time"`
State LockState `json:"state"`
Detail string `json:"detail"`
WaitMS int64 `json:"wait_ms"` // how long BEGIN IMMEDIATE waited before resolving
Holders []Holder `json:"holders,omitempty"` // processes with the file open (local only)
Hint string `json:"hint,omitempty"` // remediation hint when contended
WALExists bool `json:"wal_exists"`
}
LiveProbe is a point-in-time snapshot of who holds the lock and whether a writer can proceed. Unlike Diagnose (which reads static PRAGMA config), this observes the database as it is right now.
func Probe ¶
Probe observes the live lock state of a local SQLite database. It is read-only and side-effect-free: it opens a fresh connection, attempts to acquire the write lock with a short timeout, and immediately rolls back.
Remote sources (d1://, turso://) have no observable file-level lock, so Probe returns an error directing the caller to the static Diagnose path.
type LockState ¶
type LockState string
LockState is the live locking status of a database at one instant.
const ( StateFree LockState = "free" // a write lock can be acquired right now StateLocked LockState = "locked" // a writer currently holds the lock (SQLITE_BUSY) StateReadable LockState = "readable" // reads succeed but the write lock is contended StateError LockState = "error" // the database could not be probed )
type Report ¶
type Report struct {
Source string
Provider string // "local" | "d1" | "turso"
Pragmas map[string]string // PRAGMA values (local only)
Findings []Finding
Verdict string // "ok" | "attention" | "critical"
WALBytes int64 // WAL file size in bytes (local only)
}
Report is the full output of a lock diagnosis.
Source Files