db

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package db manages the embedded database handles.

The primary handle plus the cache handle in sqlite.go serve all traffic. New code uses the pair through OpenSQLite: durable configuration on the primary handle, rebuildable state on the cache handle.

Index

Constants

View Source
const MaxOpenConnections = 16

MaxOpenConnections caps each SQLite connection pool. SQLite serializes writers on the database lock; the pool raises read concurrency, not write concurrency. Decision D4 sets 16.

View Source
const SQLiteFileSuffix = ".sqlite3"

SQLiteFileSuffix marks the new database filename.

Variables

View Source
var ErrParentMissing = errors.New("parent directory missing")

ErrParentMissing reports a missing parent directory for a SQLite file. Managed XDG parents are created by the configuration layer before open; custom parents must exist. Match with errors.Is.

Functions

func AssertOpenState added in v0.4.0

func AssertOpenState(ctx context.Context, database *gorm.DB) error

AssertOpenState verifies the connection pragmas and SQLite version. Any failure stops startup.

func BackupTo added in v0.4.0

func BackupTo(ctx context.Context, database *gorm.DB, destination string) error

BackupTo writes a backup copy to the given destination path. The destination travels as a bound parameter.

func BuildEventsDSN added in v0.4.0

func BuildEventsDSN(path string) string

BuildEventsDSN composes the SQLite DSN for the events file. It carries the base pragmas plus incremental auto-vacuum so retention pruning reclaims disk pages without a full vacuum rewrite.

func BuildSQLiteDSN added in v0.4.0

func BuildSQLiteDSN(path string) string

BuildSQLiteDSN composes the SQLite DSN for the given file path. Foreign keys, WAL mode, synchronous NORMAL, busy timeout, immediate transaction lock, and SQLite time format are fixed by design.

func CheckIntegrity added in v0.4.0

func CheckIntegrity(ctx context.Context, database *gorm.DB) error

CheckIntegrity runs the doctor integrity check.

func FreelistCount added in v0.4.0

func FreelistCount(ctx context.Context, database *gorm.DB) (int64, error)

FreelistCount reports the number of free pages awaiting reclamation.

func Maintenance added in v0.4.0

func Maintenance(ctx context.Context, database *gorm.DB) error

Maintenance runs the allowlisted SQLite administration statements. This file owns every raw statement in the service. No other file may use Raw, Exec, or string conditions. Statements use literals, never interpolation. The backup destination travels as a bound parameter.

func NewGormConfiguration added in v0.4.0

func NewGormConfiguration() *gorm.Config

NewGormConfiguration builds the shared GORM configuration. Timestamps use UTC. Bound values stay out of logs.

func PruneEvents added in v0.4.0

func PruneEvents(ctx context.Context, eventsDatabase *gorm.DB, retentionDays int) error

PruneEvents deletes event rows older than retentionDays and reclaims freed pages. RetentionDays must be at least 1; callers validate before calling. The cutoff travels as a validated integer literal: SQLite date modifiers cannot bind as parameters.

func Translate added in v0.4.0

func Translate(err error) error

Translate maps GORM sentinel errors to domain sentinels. Matching uses errors.Is, never message text.

func Vacuum added in v0.4.0

func Vacuum(ctx context.Context, database *gorm.DB) error

Vacuum rewrites the database file to reclaim free pages. It runs on shutdown after all writers stop; the caller still closes the handle when vacuum fails.

Types

type Database added in v0.4.0

type Database struct {
	Handle *gorm.DB
	Cache  *gorm.DB
	Events *gorm.DB
}

Database wraps the primary GORM SQLite handle plus the cache and events handles. Handle owns durable configuration: providers, credentials, tokens, and installed plugins. Cache owns rebuildable state: sessions, upstream model lists, cooldown parks, telemetry, and async compat rows. Events owns operator telemetry only: deleting it while stopped loses log history and nothing else. The cache and events files may be deleted while stopped; startup recreates them empty.

func OpenSQLite added in v0.4.0

func OpenSQLite(ctx context.Context, path, cachePath, eventsPath string) (*Database, error)

OpenSQLite connects to all three SQLite files, configures the pools, asserts the open state, migrates each schema, copies legacy cache tables out of a single-file database once, and migrates the primary schema. Any failure stops startup.

func (*Database) Close added in v0.4.0

func (database *Database) Close() error

Close checkpoints all write-ahead logs, vacuums all files, optimizes them, and closes all pools. All handles close even when the first reports an error.

Directories

Path Synopsis
Package migrate owns the forward-only SQLite migration registry and runner.
Package migrate owns the forward-only SQLite migration registry and runner.
Package migrations owns numbered SQLite schema changes.
Package migrations owns numbered SQLite schema changes.
Package record owns GORM persistence structs.
Package record owns GORM persistence structs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL