PostgreSQL Store

The store/postgres package provides a production-ready implementation of the composite store.Store interface using PostgreSQL with the bun ORM.

Setup

import (
    "github.com/uptrace/bun"
    "github.com/xraph/sentinel/store/postgres"
)

db := connectDB() // your *bun.DB connection
pgStore := postgres.New(db)

// Run migrations
if err := pgStore.Migrate(ctx); err != nil {
    log.Fatal(err)
}

Tables

The PostgreSQL store creates the following tables:

JSONB columns

Complex nested structures are stored as JSONB columns:

• Case scorers and tags → scorers JSONB, tags JSONB
• Result scorer outputs and run trace → scorer_results JSONB, run_trace JSONB
• Dimension scores → dimension_scores JSONB
• All entities → metadata JSONB

Composite store interface

The PostgreSQL store implements all 5 sub-interfaces:

type Store interface {
    suite.Store         // 6 methods
    testcase.Store      // 7 methods
    evalrun.Store       // 5 methods
    baseline.Store      // 5 methods
    promptversion.Store // 5 methods

    Migrate(ctx context.Context) error
    Ping(ctx context.Context) error
    Close() error
}

Embedded migrations

Migrations are embedded in the binary using embed.FS and run automatically when Migrate() is called. There are 5 migration files:

1. 001_suites.sql — Creates sentinel_suites
2. 002_cases.sql — Creates sentinel_cases
3. 003_runs.sql — Creates sentinel_runs and sentinel_results
4. 004_baselines.sql — Creates sentinel_baselines
5. 005_prompt_versions.sql — Creates sentinel_prompt_versions

Other store backends

All three backends implement the same store.Store interface identically.

Usage with engine

eng, err := engine.New(
    engine.WithStore(pgStore),
)