SQLite Store

The store/sqlite package implements Chronicle's store.Store interface using SQLite via the modernc.org/sqlite pure-Go driver. It requires no CGO and no external database process, making it ideal for development, integration tests, and single-node deployments that don't need horizontal scaling.

Import

import (
    "database/sql"

    "github.com/xraph/chronicle/store/sqlite"
)

Constructors

`sqlite.Open` — recommended

Opens a SQLite file by path, enables WAL mode, and enforces foreign keys automatically:

s, err := sqlite.Open("./chronicle.db")
if err != nil {
    log.Fatal(err)
}

Pass ":memory:" for a fully in-process, zero-persistence store (useful in tests):

s, err := sqlite.Open(":memory:")

`sqlite.New` — bring your own `*sql.DB`

If you already manage the *sql.DB connection (e.g. for connection sharing), pass it directly:

db, err := sql.Open("sqlite", "./chronicle.db")
if err != nil {
    log.Fatal(err)
}

s := sqlite.New(db)

Note: when using sqlite.New, WAL mode and foreign key enforcement are not applied automatically. Set them yourself before passing the connection:

db.ExecContext(ctx, "PRAGMA journal_mode=WAL")
db.ExecContext(ctx, "PRAGMA foreign_keys=ON")

Migrations

Run schema migrations before first use. Migrations are embedded SQL files executed inside a single transaction:

if err := s.Migrate(ctx); err != nil {
    log.Fatal(err)
}

Migrations are idempotent — safe to run on every startup.

Full setup with `chronicle.New`

import (
    "context"
    "log"

    "github.com/xraph/chronicle"
    "github.com/xraph/chronicle/store"
    "github.com/xraph/chronicle/store/sqlite"
)

ctx := context.Background()

s, err := sqlite.Open("./chronicle.db")
if err != nil {
    log.Fatal(err)
}

if err := s.Migrate(ctx); err != nil {
    log.Fatal(err)
}

adapter := store.NewAdapter(s)

c, err := chronicle.New(chronicle.WithStore(adapter))
if err != nil {
    log.Fatal(err)
}

With the Forge extension

import "github.com/xraph/chronicle/extension"

s, err := sqlite.Open("./chronicle.db")
if err != nil {
    log.Fatal(err)
}

ext := extension.New(
    extension.WithStore(s),
    // Migrate runs automatically on Start unless WithDisableMigrate(true)
)
app.Register(ext)

Interfaces implemented

sqlite.Store satisfies:

audit.Store
stream.Store
verify.Store
erasure.Store
retention.Store
compliance.ReportStore
store.Store (composite)

Characteristics

Aspect	Detail
Driver	`modernc.org/sqlite` (pure Go, no CGO)
Migrations	Embedded SQL, transaction-wrapped
WAL mode	Enabled automatically by `Open` for concurrent reads
Foreign keys	Enforced automatically by `Open`
Concurrency	Multiple readers, single writer
Persistence	File-based (`Open`) or in-process (`":memory:"`)
Recommended for	Development, integration tests, single-node deployments
Not recommended for	High-throughput multi-writer production workloads

SQLite Store

On this page