Documentation
¶
Overview ¶
Package sqlite provides the SQLite persistence layer for the Provenance task dependency tracker. It implements all CRUD operations for tasks, edges, agents, labels, comments, and activities.
This package imports pkg/ptypes for all type definitions and uses zombiezen.com/go/sqlite for pure-Go SQLite access (no CGo required at runtime, though CGo tests use the C library for the race detector).
The DB struct holds a single SQLite connection guarded by a sync.Mutex. All exported methods acquire the mutex before accessing the connection.
Index ¶
- func ScanActivity(stmt *zs.Stmt) (ptypes.Activity, error)
- func ScanComment(stmt *zs.Stmt) (ptypes.Comment, error)
- func ScanTask(stmt *zs.Stmt) (ptypes.Task, error)
- func TimeToNullInt(t *time.Time) any
- type DB
- func (db *DB) AddComment(id ptypes.TaskID, authorID ptypes.AgentID, body string) (ptypes.Comment, error)
- func (db *DB) AddLabel(id ptypes.TaskID, label string) error
- func (db *DB) BlockedTasks() ([]ptypes.Task, error)
- func (db *DB) Close() error
- func (db *DB) CloseTask(id ptypes.TaskID, reason string, now time.Time) (ptypes.Task, error)
- func (db *DB) Conn() *zs.Conn
- func (db *DB) DeleteEdge(sourceID ptypes.TaskID, targetID string, kind ptypes.EdgeKind) error
- func (db *DB) EndActivity(id ptypes.ActivityID) (ptypes.Activity, error)
- func (db *DB) GetActivities(agentID *ptypes.AgentID) ([]ptypes.Activity, error)
- func (db *DB) GetAgent(id ptypes.AgentID) (ptypes.Agent, error)
- func (db *DB) GetBlockedByEdges() ([]ptypes.Edge, error)
- func (db *DB) GetComments(id ptypes.TaskID) ([]ptypes.Comment, error)
- func (db *DB) GetDepTree(rootID ptypes.TaskID) ([]ptypes.Edge, error)
- func (db *DB) GetEdges(sourceID ptypes.TaskID, kind *ptypes.EdgeKind) ([]ptypes.Edge, error)
- func (db *DB) GetHumanAgent(id ptypes.AgentID) (ptypes.HumanAgent, error)
- func (db *DB) GetLabels(id ptypes.TaskID) ([]string, error)
- func (db *DB) GetMLAgent(id ptypes.AgentID) (ptypes.MLAgent, error)
- func (db *DB) GetSoftwareAgent(id ptypes.AgentID) (ptypes.SoftwareAgent, error)
- func (db *DB) GetTask(id ptypes.TaskID) (ptypes.Task, bool, error)
- func (db *DB) InsertEdge(sourceID ptypes.TaskID, targetID string, kind ptypes.EdgeKind, now time.Time) error
- func (db *DB) InsertTask(task ptypes.Task) error
- func (db *DB) ListTasks(filter ptypes.ListFilter) ([]ptypes.Task, error)
- func (db *DB) Lock()
- func (db *DB) ReadyTasks() ([]ptypes.Task, error)
- func (db *DB) RegisterHumanAgent(namespace, name, contact string) (ptypes.HumanAgent, error)
- func (db *DB) RegisterMLAgent(namespace string, role ptypes.Role, provider ptypes.Provider, ...) (ptypes.MLAgent, error)
- func (db *DB) RegisterSoftwareAgent(namespace, name, version, source string) (ptypes.SoftwareAgent, error)
- func (db *DB) RemoveLabel(id ptypes.TaskID, label string) error
- func (db *DB) StartActivity(agentID ptypes.AgentID, phase ptypes.Phase, stage ptypes.Stage, notes string) (ptypes.Activity, error)
- func (db *DB) StartActivityWithID(id ptypes.ActivityID, agentID ptypes.AgentID, phase ptypes.Phase, ...) (ptypes.Activity, error)
- func (db *DB) TaskCount() (int, error)
- func (db *DB) Unlock()
- func (db *DB) UpdateTask(id ptypes.TaskID, fields ptypes.UpdateFields, now time.Time) (ptypes.Task, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ScanActivity ¶
ScanActivity converts a SQL result row into a ptypes.Activity. The stmt must select:
id, agent_id, phase_id, stage_id, started_at, ended_at, notes
(7 columns, indexed 0–6).
func ScanComment ¶
ScanComment converts a SQL result row into a ptypes.Comment. The stmt must select:
id, task_id, author_id, body, created_at
(5 columns, indexed 0–4).
func ScanTask ¶
ScanTask converts a SQL result row into a ptypes.Task. The stmt must select:
id, namespace, title, description, status_id, priority_id, type_id, phase_id, owner_id, notes, created_at, updated_at, closed_at, close_reason
(14 columns, indexed 0–13).
func TimeToNullInt ¶
TimeToNullInt converts *time.Time to a nullable int64 value for SQLite. Returns nil if t is nil, otherwise returns t.UnixNano().
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB wraps a single SQLite connection with a mutex for safe concurrent access. Use Open to create a new DB instance.
func Open ¶
func Open(dbPath string, models []ptypes.ModelEntry) (*DB, error)
Open opens (or creates) a SQLite database at dbPath and returns an initialised DB. Pass ":memory:" for an in-memory database.
The schema is applied idempotently on every open (CREATE TABLE IF NOT EXISTS). Reference data (enums) is inserted via INSERT OR IGNORE. The models parameter provides the ML model entries to seed into ml_models.
func (*DB) AddComment ¶
func (db *DB) AddComment(id ptypes.TaskID, authorID ptypes.AgentID, body string) (ptypes.Comment, error)
AddComment adds a comment to a task authored by authorID. A UUIDv7 CommentID is assigned automatically. Acquires the DB mutex.
func (*DB) AddLabel ¶
AddLabel attaches a label to a task. Idempotent (INSERT OR IGNORE). Acquires the DB mutex.
func (*DB) BlockedTasks ¶
BlockedTasks returns tasks that are not closed and have at least one open blocker. Acquires the DB mutex.
func (*DB) CloseTask ¶
CloseTask marks a task as closed with the given reason. Returns the updated task. Returns ptypes.ErrNotFound if the task does not exist after the update. Acquires the DB mutex.
func (*DB) Conn ¶
Conn returns the underlying SQLite connection. This is exposed so that the root package's graphStore can access the connection for vertex/edge operations without duplicating SQL. The caller MUST hold the DB mutex (via Lock/Unlock) when using this connection.
func (*DB) DeleteEdge ¶
DeleteEdge deletes an edge. Acquires the DB mutex.
func (*DB) EndActivity ¶
EndActivity records the end time of an activity. Returns the updated activity. Returns ptypes.ErrNotFound if the activity does not exist. Acquires the DB mutex.
func (*DB) GetActivities ¶
GetActivities returns all activities, optionally filtered by agent. Pass nil to return activities for all agents. Acquires the DB mutex.
func (*DB) GetAgent ¶
GetAgent returns the base agent (kind only) by ID. Returns ptypes.ErrNotFound if the agent does not exist. Acquires the DB mutex.
func (*DB) GetBlockedByEdges ¶
GetBlockedByEdges returns all EdgeBlockedBy edges in the database. Acquires the DB mutex.
func (*DB) GetComments ¶
GetComments returns all comments on a task in chronological order. Acquires the DB mutex.
func (*DB) GetDepTree ¶
GetDepTree returns all blocked-by edges reachable from rootID via DFS. The result is in DFS traversal order. Acquires the DB mutex.
func (*DB) GetEdges ¶
GetEdges returns edges originating from sourceID, optionally filtered by kind. Pass nil for kind to get all edge kinds. Acquires the DB mutex.
func (*DB) GetHumanAgent ¶
GetHumanAgent returns the human agent by ID. Returns ptypes.ErrNotFound if not found or if the agent is a different kind. Acquires the DB mutex.
func (*DB) GetLabels ¶
GetLabels returns all labels attached to a task, sorted alphabetically. Acquires the DB mutex.
func (*DB) GetMLAgent ¶
GetMLAgent returns the ML agent by ID. Returns ptypes.ErrNotFound if not found or if the agent is a different kind. Acquires the DB mutex.
func (*DB) GetSoftwareAgent ¶
GetSoftwareAgent returns the software agent by ID. Returns ptypes.ErrNotFound if not found or if the agent is a different kind. Acquires the DB mutex.
func (*DB) GetTask ¶
GetTask retrieves a task by ID. Returns (task, true, nil) if found, (zero, false, nil) if not found, or (zero, false, err) on error. Acquires the DB mutex.
func (*DB) InsertEdge ¶
func (db *DB) InsertEdge(sourceID ptypes.TaskID, targetID string, kind ptypes.EdgeKind, now time.Time) error
InsertEdge inserts a typed edge. Acquires the DB mutex.
func (*DB) InsertTask ¶
InsertTask inserts a task row into the tasks table. Acquires the DB mutex.
func (*DB) ListTasks ¶
ListTasks returns tasks matching the given filter. An empty filter returns all tasks ordered by creation time (ascending). Acquires the DB mutex.
func (*DB) Lock ¶
func (db *DB) Lock()
Lock acquires the DB mutex. Use this when you need direct access to Conn().
func (*DB) ReadyTasks ¶
ReadyTasks returns tasks that are not closed and have no open blockers. Acquires the DB mutex.
func (*DB) RegisterHumanAgent ¶
func (db *DB) RegisterHumanAgent(namespace, name, contact string) (ptypes.HumanAgent, error)
RegisterHumanAgent registers a new human agent with a UUIDv7 ID. Acquires the DB mutex.
func (*DB) RegisterMLAgent ¶
func (db *DB) RegisterMLAgent(namespace string, role ptypes.Role, provider ptypes.Provider, modelName ptypes.ModelID) (ptypes.MLAgent, error)
RegisterMLAgent registers a new ML agent. The (provider, modelName) pair must exist in the ml_models seed table; returns ptypes.ErrNotFound if unknown. Acquires the DB mutex.
func (*DB) RegisterSoftwareAgent ¶
func (db *DB) RegisterSoftwareAgent(namespace, name, version, source string) (ptypes.SoftwareAgent, error)
RegisterSoftwareAgent registers a new software agent with a UUIDv7 ID. Acquires the DB mutex.
func (*DB) RemoveLabel ¶
RemoveLabel detaches a label from a task. Idempotent (no error if not present). Acquires the DB mutex.
func (*DB) StartActivity ¶
func (db *DB) StartActivity(agentID ptypes.AgentID, phase ptypes.Phase, stage ptypes.Stage, notes string) (ptypes.Activity, error)
StartActivity records the start of an activity for the given agent. A UUIDv7 ActivityID is assigned automatically. Acquires the DB mutex.
func (*DB) StartActivityWithID ¶ added in v0.0.2
func (db *DB) StartActivityWithID(id ptypes.ActivityID, agentID ptypes.AgentID, phase ptypes.Phase, stage ptypes.Stage, notes string) (ptypes.Activity, error)
StartActivityWithID records the start of an activity using a CALLER-SUPPLIED ActivityID, idempotently. Unlike StartActivity (which mints a random UUIDv7), the caller owns the id; a second call with the same id is a no-op (INSERT ... ON CONFLICT(id) DO NOTHING) and the existing row is returned. This makes activity emission safe to replay — e.g. when a durable-workflow step re-executes after a crash, a deterministic id (such as a name-based UUIDv5 over the workflow's logical identity) collapses the duplicate to one row. Acquires the DB mutex.
Source Files