---
title: internal/db
description: Go API reference for the db package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# db

```go
import "github.com/jbcom/radioactive-ralph/internal/db"
```

Package db is radioactive\-ralph's per\-repo SQLite event log.

Every interesting thing the supervisor does is recorded as an event here: session spawns, user messages injected into managed Claude subprocesses, stream\-json events received, session deaths, resumes, commits, PRs, errors. The database is an append\-only log the supervisor replays on startup to rebuild in\-memory state.

SQLite is opened with journal\_mode=WAL so the supervisor \(single writer\) and status/attach readers \(many readers\) can coexist without locking. foreign\_keys=ON for referential integrity on sessions\<\-\>spend. busy\_timeout=5000 so brief writer contention during reader checkpoint doesn't crash the supervisor.

Dedup uses SQLite's built\-in FTS5 virtual table over task descriptions. Full semantic search \(sqlite\-vec\) was scoped out of M2 because it requires an embeddings pipeline we don't want to own yet.

## Index

- [Constants](<#constants>)
- [type DB](<#DB>)
  - [func Open\(ctx context.Context, path string\) \(\*DB, error\)](<#Open>)
  - [func \(d \*DB\) AccumulateSpend\(ctx context.Context, sessionUUID, model string, input, output, cached int64\) error](<#DB.AccumulateSpend>)
  - [func \(d \*DB\) ActiveSessions\(ctx context.Context\) \(\[\]Session, error\)](<#DB.ActiveSessions>)
  - [func \(d \*DB\) Append\(ctx context.Context, e Event\) \(int64, error\)](<#DB.Append>)
  - [func \(d \*DB\) ClaimTask\(ctx context.Context, taskID, worktreePath, sessionUUID string\) error](<#DB.ClaimTask>)
  - [func \(d \*DB\) Close\(\) error](<#DB.Close>)
  - [func \(d \*DB\) Conn\(\) \*sql.DB](<#DB.Conn>)
  - [func \(d \*DB\) EnqueueTask\(ctx context.Context, id, description string, priority int\) \(string, bool, error\)](<#DB.EnqueueTask>)
  - [func \(d \*DB\) FinishTask\(ctx context.Context, taskID string, success bool\) error](<#DB.FinishTask>)
  - [func \(d \*DB\) InsertSession\(ctx context.Context, s Session\) error](<#DB.InsertSession>)
  - [func \(d \*DB\) ListTasks\(ctx context.Context, statuses ...string\) \(\[\]Task, error\)](<#DB.ListTasks>)
  - [func \(d \*DB\) MarkSessionExited\(ctx context.Context, uuid, reason string\) error](<#DB.MarkSessionExited>)
  - [func \(d \*DB\) Path\(\) string](<#DB.Path>)
  - [func \(d \*DB\) Replay\(ctx context.Context, afterID int64, fn func\(Event\) error\) error](<#DB.Replay>)
  - [func \(d \*DB\) SpendBySession\(ctx context.Context, sessionUUID string\) \(\[\]Spend, error\)](<#DB.SpendBySession>)
- [type Event](<#Event>)
- [type Session](<#Session>)
- [type Spend](<#Spend>)
- [type Task](<#Task>)


## Constants

<a name="TaskQueued"></a>TaskStatus values map to the tasks.status column.

```go
const (
    TaskQueued  = "queued"
    TaskRunning = "running"
    TaskBlocked = "blocked"
    TaskDone    = "done"
    TaskFailed  = "failed"
)
```

<a name="DriverName"></a>DriverName is the modernc.org/sqlite driver identifier. Exposed so tests can open in\-memory databases directly.

```go
const DriverName = "sqlite"
```

<a name="DB"></a>
## type [DB](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L43-L46>)

DB is the package's wrapper around \*sql.DB with the supervisor's helper methods attached. Construct via Open.

```go
type DB struct {
    // contains filtered or unexported fields
}
```

<a name="Open"></a>
### func [Open](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L53>)

```go
func Open(ctx context.Context, path string) (*DB, error)
```

Open opens the SQLite database at path \(creating it if absent\), applies pending migrations, and returns a \*DB ready for use.

path is typically xdg.Paths.StateDB. An empty string opens an in\-memory database, which is what tests want.

<a name="DB.AccumulateSpend"></a>
### func \(\*DB\) [AccumulateSpend](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L437>)

```go
func (d *DB) AccumulateSpend(ctx context.Context, sessionUUID, model string, input, output, cached int64) error
```

AccumulateSpend upserts token counts for a \(session, model\) pair. Input/output/cached values are additive — each call adds to the existing totals.

<a name="DB.ActiveSessions"></a>
### func \(\*DB\) [ActiveSessions](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L405>)

```go
func (d *DB) ActiveSessions(ctx context.Context) ([]Session, error)
```

ActiveSessions returns sessions that haven't exited yet.

<a name="DB.Append"></a>
### func \(\*DB\) [Append](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L129>)

```go
func (d *DB) Append(ctx context.Context, e Event) (int64, error)
```

Append inserts an event. PayloadParsed is JSON\-encoded if non\-nil.

<a name="DB.ClaimTask"></a>
### func \(\*DB\) [ClaimTask](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L270>)

```go
func (d *DB) ClaimTask(ctx context.Context, taskID, worktreePath, sessionUUID string) error
```

ClaimTask marks a queued task as running and sets the worktree \+ session.

<a name="DB.Close"></a>
### func \(\*DB\) [Close](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L83>)

```go
func (d *DB) Close() error
```

Close releases the underlying connection pool.

<a name="DB.Conn"></a>
### func \(\*DB\) [Conn](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L96>)

```go
func (d *DB) Conn() *sql.DB
```

Conn returns the underlying \*sql.DB. Exposed for advanced callers \(integration tests that want to assert schema directly\); most supervisor code should use the typed methods on DB.

<a name="DB.EnqueueTask"></a>
### func \(\*DB\) [EnqueueTask](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L232>)

```go
func (d *DB) EnqueueTask(ctx context.Context, id, description string, priority int) (string, bool, error)
```

EnqueueTask inserts a new task and returns its ID. If a near\-duplicate description already exists with status in \(queued, running\), the existing task ID is returned and a new row is NOT inserted. Dedup uses FTS5's MATCH against the normalised description.

<a name="DB.FinishTask"></a>
### func \(\*DB\) [FinishTask](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L292>)

```go
func (d *DB) FinishTask(ctx context.Context, taskID string, success bool) error
```

FinishTask marks a task as done or failed.

<a name="DB.InsertSession"></a>
### func \(\*DB\) [InsertSession](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L377>)

```go
func (d *DB) InsertSession(ctx context.Context, s Session) error
```

InsertSession records a newly\-spawned managed session.

<a name="DB.ListTasks"></a>
### func \(\*DB\) [ListTasks](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L311>)

```go
func (d *DB) ListTasks(ctx context.Context, statuses ...string) ([]Task, error)
```

ListTasks returns tasks matching the given statuses, most recent first. Pass nil or empty statuses to return all statuses.

<a name="DB.MarkSessionExited"></a>
### func \(\*DB\) [MarkSessionExited](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L390>)

```go
func (d *DB) MarkSessionExited(ctx context.Context, uuid, reason string) error
```

MarkSessionExited records why and when a session ended.

<a name="DB.Path"></a>
### func \(\*DB\) [Path](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L89>)

```go
func (d *DB) Path() string
```

Path returns the on\-disk path of the database \(empty string for in\-memory\).

<a name="DB.Replay"></a>
### func \(\*DB\) [Replay](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L161>)

```go
func (d *DB) Replay(ctx context.Context, afterID int64, fn func(Event) error) error
```

Replay iterates events in ID order \(which is also approximately timestamp order\) and yields them via the callback. The callback's returned error aborts iteration and is propagated to the caller.

afterID lets the caller resume from a previous replay's last\-seen ID. Pass 0 to iterate from the beginning.

<a name="DB.SpendBySession"></a>
### func \(\*DB\) [SpendBySession](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L464>)

```go
func (d *DB) SpendBySession(ctx context.Context, sessionUUID string) ([]Spend, error)
```

SpendBySession returns all \(model, spend\) entries for one session.

<a name="Event"></a>
## type [Event](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L118-L126>)

Event is the structured form of an entry in the events table. PayloadRaw holds the exact bytes received from stream\-json \(nil if the event originated inside the supervisor\).

```go
type Event struct {
    ID            int64
    Timestamp     time.Time
    Stream        string
    Kind          string
    Actor         string
    PayloadParsed any // marshalled to JSON before insert
    PayloadRaw    []byte
}
```

<a name="Session"></a>
## type [Session](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L364-L374>)

Session is the row shape of the sessions table.

```go
type Session struct {
    UUID         string
    Variant      string
    WorktreePath string
    PID          int
    Model        string
    Stage        string
    StartedAt    time.Time
    ExitedAt     *time.Time
    ExitReason   string
}
```

<a name="Spend"></a>
## type [Spend](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L455-L461>)

Spend is the row shape of the spend table.

```go
type Spend struct {
    SessionUUID  string
    Model        string
    InputTokens  int64
    OutputTokens int64
    CachedInput  int64
}
```

<a name="Task"></a>
## type [Task](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/db/db.go#L217-L226>)

Task is a queued unit of work.

```go
type Task struct {
    ID           string
    Description  string
    Priority     int
    Status       string
    WorktreePath string
    ClaimedBy    string
    CreatedAt    time.Time
    UpdatedAt    time.Time
}
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)