add-store-query

Add a query (and optionally a migration) to the store

pkg/store/ is the SQLite layer. Queries are SQL string constants in queries.go; methods on *Store execute them through s.Tx(...) for writes or s.db.QueryContext(...) for reads. Schema lives in migrations/000N_*.sql, embedded via embed.FS and applied at startup.

There are two workflows here. Pick the right one before you start.

Need new SQL only?  ──> Workflow A (query)
Need a new column / table / index?  ──> Workflow A + Workflow B (migration)

Workflow A — add a query and method

Three files. Same pattern every time.

File	What changes
pkg/store/queries.go	Add a q<Verb><Noun> = ... const
pkg/store/<domain>.go	Add the method on *Store (temperature.go, node.go, search.go, snapshot.go — pick the matching domain)
pkg/store/store_test.go	Add a test that opens testutil.OpenTestDB(t) and exercises the method

Query const

Constants are grouped at the bottom of queries.go next to related queries. Name them q<Verb><Noun> — e.g., qSelectColdNodes, qBoostTemperature, qIncrementAccess. No package prefix; the file is the namespace.

const qListSourceFiles = `SELECT DISTINCT source_file FROM nodes ORDER BY source_file`

For batch queries with a variable IN list, follow the qBoostTemperatureBatchPrefix pattern: define the prefix as a const, append placeholders + ) in the calling method.

Method shape

Two flavors based on read vs write.

Reads call s.db.QueryContext directly, defer rows.Close(), and return through collectRows (or a dedicated row-scanner if the columns differ from nodeColumns). Reads do not wrap in s.Tx(...).

func (s *Store) ListSourceFiles(ctx context.Context) ([]string, error) {
    rows, err := s.db.QueryContext(ctx, qListSourceFiles)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()

    var out []string
    for rows.Next() {
        var path string
        if err := rows.Scan(&path); err != nil {
            return nil, err
        }
        out = append(out, path)
    }
    return out, rows.Err()
}