db

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package db opens the application's database and manages its schema.

d := db.MustOpen(cfg.DB, db.Tables(
	db.Table(&Post{}, db.SoftUnique("uk_post_title_owner", "title", "owner_id")),
	db.Table(&Like{}, db.Unique("uk_like_owner_post", "owner_id", "post_id")),
))
app.Use(d) // health, and close after everything that uses it

Three dialects stand on equal footing: sqlite (pure Go), mysql and postgres; every battery and every test runs on all three.

Models

A model embeds one of four bases: Model (a numeric key that stays internal, a public RID, an optimistic-lock version, timestamps), SoftDeleteModel, OwnedModel or OwnedSoftDeleteModel. RIDPrefixer names the RIDs: pst_3fK9aQ2mZx7B.

Migrations

db.migrate picks one of three modes, applied at Open to the application's schema and at RegisterSchema to each battery's:

  • auto: AutoMigrate the declared tables and create their Unique and SoftUnique indexes; an index that already has a declared name must match its declaration, or migrating fails. The default, for development and small services.
  • versioned: apply the SQL files given to Migrations, named <14-digit version>_<name>.sql, forward only. One ledger table, chok_migrations, records them per owner ("app" and each battery). An edited applied file is ErrChecksumDrift; MarkApplied is the one manual intervention.
  • off: touch nothing, but refuse to start (ErrNotMigrated) while a versioned file is pending — for processes that should never migrate.

SQLite and Postgres apply each file in one transaction. MySQL commits DDL implicitly, so it runs a file statement by statement and records each one: a file that fails halfway resumes after the last statement that ran, once the failing one is fixed. A Postgres advisory lock or a MySQL GET_LOCK keeps concurrent processes from migrating twice.

MySQL

Sessions run in UTC (parseTime=true, loc=UTC, time_zone '+00:00'), so a time.Time stores as its UTC wall clock whatever the host's zone, and the zone is not configurable. Identifiers chok generates are not quoted against reserved words: name no column key, order or group.

Transactions

RunInTx puts the transaction in the context it hands fn: stores and Unsafe called with that context join it, a nested RunInTx joins it, and AfterCommit defers work until it commits. Unsafe is the only way to the underlying *gorm.DB.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotMigrated is returned with migrate: off when versioned files
	// are not all applied, so a process never runs on a stale schema.
	ErrNotMigrated = errors.New("db: migrations are not applied")
	// ErrChecksumDrift is returned when an applied migration's file has
	// changed: migrations only move forward, so fix it with a new one.
	ErrChecksumDrift = errors.New("db: an applied migration has changed")
)

Functions

func NewRID added in v0.2.0

func NewRID(prefix string) string

NewRID returns a fresh RID with prefix. It panics on a prefix that is not 1–10 characters of [a-z0-9] starting with a letter, which is a programming error.

Example
package main

import (
	"fmt"

	"github.com/zynthara/chok/db"
)

func main() {
	rid := db.NewRID("pst")
	prefix, ok := db.ParseRID(rid)
	fmt.Println(prefix, ok, len(rid))
}
Output:
pst true 16

func ParseRID added in v0.2.0

func ParseRID(rid string) (prefix string, ok bool)

ParseRID returns the prefix of rid and whether rid is well formed. A RID without an underscore is well formed and has no prefix.

Types

type Config added in v0.2.0

type Config struct {
	Driver string `yaml:"driver" validate:"oneof=sqlite mysql postgres"`
	// Migrate is auto (AutoMigrate the declared tables), versioned (apply
	// the SQL files given to Migrations) or off (touch nothing, but fail
	// if versioned files are pending).
	Migrate string `yaml:"migrate" default:"auto" validate:"oneof=auto versioned off"`
	// MigrationTimeout bounds one owner's schema work, including lock and pool wait.
	// Open and RegisterSchema run before App.Run and use this separate budget.
	MigrationTimeout time.Duration `yaml:"migration_timeout" default:"30s" validate:"gte=0"`
	// SlowThreshold logs queries slower than it at warn; 0 disables.
	SlowThreshold time.Duration  `yaml:"slow_threshold" default:"200ms" validate:"gte=0"`
	SQLite        SQLiteConfig   `yaml:"sqlite"`
	MySQL         MySQLConfig    `yaml:"mysql"`
	Postgres      PostgresConfig `yaml:"postgres"`
	// Pool sizes the connection pool of MySQL and Postgres, and the read
	// pool of a SQLite file.
	Pool PoolConfig `yaml:"pool"`
	// Store is the default posture of every store.Store on this handle.
	Store StorePolicy `yaml:"store"`
}

Config is the db section.

func (*Config) Validate added in v0.2.0

func (c *Config) Validate() error

Validate checks what tags cannot: the fields the chosen driver needs.

type DB added in v0.2.0

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

DB is an open database: a gorm handle behind a narrow API, the schemas registered on it and, for SQLite, its maintenance. Register it with app.Use: it reports health and closes last of what used it.

func MustOpen added in v0.2.0

func MustOpen(cfg Config, opts ...Option) *DB

MustOpen is Open that panics on error.

func Open added in v0.2.0

func Open(cfg Config, opts ...Option) (*DB, error)

Open connects, applies the migrate mode to the application's schema and returns the handle. A Config from chok.Load carries every default; one built in code is used as written, except that an empty Migrate is auto.

Example
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/zynthara/chok/db"
)

type Post struct {
	db.OwnedSoftDeleteModel
	Title string `gorm:"size:200;not null"`
}

func (Post) RIDPrefix() string { return "pst" }

func main() {
	dir, _ := os.MkdirTemp("", "chok-example")
	defer func() { _ = os.RemoveAll(dir) }()
	d, err := db.Open(db.Config{Driver: "sqlite", SQLite: db.SQLiteConfig{Path: filepath.Join(dir, "app.db")}},
		db.Tables(db.Table(&Post{}, db.SoftUnique("uk_post_title_owner", "title", "owner_id"))))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer func() { _ = d.Close(context.Background()) }()
	fmt.Println(d.Unsafe(context.Background()).Migrator().HasTable(&Post{}))
}
Output:
true

func (*DB) AfterCommit added in v0.2.0

func (d *DB) AfterCommit(ctx context.Context, fn func(ctx context.Context)) bool

AfterCommit stages fn to run after the transaction in ctx commits, in staging order, with a context that is no longer transactional; a rollback drops it. Outside a transaction it does nothing and returns false. Callbacks are synchronous and best effort, retain the caller's cancellation, and are lost on a crash; use a transactional outbox when execution must be durable.

func (*DB) Close added in v0.2.0

func (d *DB) Close(ctx context.Context) error

Close stops the SQLite maintenance, running a last PRAGMA optimize when ctx allows, and closes the pools.

func (*DB) Health added in v0.2.0

func (d *DB) Health(ctx context.Context) error

Health pings the database, and the read pool of a SQLite file.

func (*DB) InTx added in v0.2.0

func (d *DB) InTx(ctx context.Context) bool

InTx reports whether ctx carries a transaction of this handle.

func (*DB) Logger added in v0.2.0

func (d *DB) Logger() *slog.Logger

Logger returns the handle's logger.

func (*DB) MarkApplied added in v0.2.0

func (d *DB) MarkApplied(ctx context.Context, version string) error

MarkApplied records the migration with version as applied without running it — the one manual intervention, for a schema repaired by hand. The version must belong to exactly one registered schema.

func (*DB) Migrate added in v0.2.0

func (d *DB) Migrate(ctx context.Context) error

Migrate applies the migrate mode to every registered schema: auto migrates the tables and their Unique and SoftUnique indexes, versioned applies the pending files, off checks that none is pending. Open and RegisterSchema already did this; the CLI and tests call it again.

func (*DB) MigrationStatus added in v0.2.0

func (d *DB) MigrationStatus(ctx context.Context) ([]MigrationStatus, error)

MigrationStatus lists the versioned migrations of every registered schema with their state.

func (*DB) Name added in v0.2.0

func (d *DB) Name() string

Name is "db", the handle's name in the health report.

func (*DB) RegisterSchema added in v0.2.0

func (d *DB) RegisterSchema(owner string, tables []TableSpec, migrations fs.FS) error

RegisterSchema adds a battery's tables and migrations under its own owner and applies the migrate mode to them now. Batteries call it from their constructors; applications declare theirs with Tables and Migrations.

func (*DB) RunInTx added in v0.2.0

func (d *DB) RunInTx(ctx context.Context, fn func(txCtx context.Context) error) error

RunInTx runs fn in a transaction whose context is txCtx: every store and Unsafe call made with txCtx joins it. fn's error rolls it back, so does a panic, which is re-raised. A RunInTx inside another joins the outer transaction of the same handle; the outermost commit is the only one. Nesting a different handle is rejected because its context would hide the outer transaction. There is no cross-database atomicity.

Example
package main

import (
	"context"
	"fmt"

	"github.com/zynthara/chok/db"
)

type Post struct {
	db.OwnedSoftDeleteModel
	Title string `gorm:"size:200;not null"`
}

func (Post) RIDPrefix() string { return "pst" }

func main() {
	d, _ := db.Open(db.Config{Driver: "sqlite", SQLite: db.SQLiteConfig{Path: ":memory:"}}, db.Tables(db.Table(&Post{})))
	defer func() { _ = d.Close(context.Background()) }()
	err := d.RunInTx(context.Background(), func(tx context.Context) error {
		d.AfterCommit(tx, func(context.Context) { fmt.Println("committed") })
		return d.Unsafe(tx).Create(&Post{Title: "hello", OwnerID: "u1"}).Error
	})
	fmt.Println(err)
}
Output:
committed
<nil>

func (*DB) StorePolicy added in v0.2.0

func (d *DB) StorePolicy() StorePolicy

StorePolicy returns db.store, the posture stores on this handle start from.

func (*DB) Unsafe added in v0.2.0

func (d *DB) Unsafe(ctx context.Context) *gorm.DB

Unsafe returns the *gorm.DB for ctx: the transaction RunInTx started, or the handle. It is the one way to gorm and raw SQL; nothing outside db and store hands *gorm.DB around. It carries none of a store's fences, neither the owner scope nor the custom scopes: for a query fenced like the store's, use (*store.Store[T]).Unsafe.

type Index added in v0.2.0

type Index struct {
	// contains filtered or unexported fields
}

Index is one index declaration of Table: SoftUnique or Unique.

func SoftUnique

func SoftUnique(name string, columns ...string) Index

SoftUnique is a unique index over columns among live rows: UNIQUE(columns..., delete_token). A soft delete writes a random token, so the deleted row stops holding the values. The same index on every dialect; Table accepts it only on a model with soft delete. It panics without a name or a column.

func Unique added in v0.2.0

func Unique(name string, columns ...string) Index

Unique is a unique index over columns among all rows: UNIQUE(columns...), the same index on every dialect, on a model with any base. An owned model without soft delete keeps a value unique per owner:

db.Table(&Like{}, db.Unique("uk_like_owner_post", "owner_id", "post_id"))

On a soft-delete model a deleted row still holds its Unique values: use Unique for a value that is never reused and SoftUnique for one a delete releases. It panics without a name or a column.

Example
package main

import (
	"context"
	"fmt"

	"github.com/zynthara/chok/db"
)

// Like has an owner and no soft delete: one like per owner and post.
type Like struct {
	db.OwnedModel
	PostID string `gorm:"size:24;not null"`
}

func main() {
	d, err := db.Open(db.Config{Driver: "sqlite", SQLite: db.SQLiteConfig{Path: ":memory:"}},
		db.Tables(db.Table(&Like{}, db.Unique("uk_like_owner_post", "owner_id", "post_id"))))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer func() { _ = d.Close(context.Background()) }()
	like := func(owner, post string) bool {
		l := &Like{PostID: post}
		l.SetOwnerID(owner)
		return d.Unsafe(context.Background()).Create(l).Error == nil
	}
	fmt.Println(like("u1", "pst_1"), like("u2", "pst_1"), like("u1", "pst_1"))
}
Output:
true true false

type MigrationStatus added in v0.2.0

type MigrationStatus struct {
	Owner   string
	Version string
	Name    string
	// State is "applied", "pending", "partial" (MySQL: the statements
	// before the failing one are applied), "drifted" (applied, but the
	// file changed since) or "missing" (applied, but the file is gone).
	State     string
	AppliedAt time.Time
	// Statements counts the statements that have run.
	Statements int
}

MigrationStatus is one versioned migration of one owner.

type Model

type Model struct {
	ID        uint      `json:"-" gorm:"primaryKey"`
	RID       string    `json:"id" gorm:"column:rid;uniqueIndex;size:24;not null"`
	Version   int       `json:"version" gorm:"default:1;not null"`
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime"`
	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime"`
}

Model is the base of a model: a numeric key that stays internal, a public RID (json "id"), an optimistic-lock version and timestamps.

func (*Model) BeforeCreate

func (m *Model) BeforeCreate(tx *gorm.DB) error

BeforeCreate starts the version at 1 and assigns a RID with the model's prefix unless one is set; a preset RID must be well formed.

type Modeler

type Modeler interface {
	// contains filtered or unexported methods
}

Modeler is satisfied only by the four model bases, through an unexported method: embed one of them to make a struct a model.

type MySQLConfig added in v0.2.0

type MySQLConfig struct {
	Host     string `yaml:"host" default:"127.0.0.1"`
	Port     int    `yaml:"port" default:"3306" validate:"gte=0,lte=65535"`
	Username string `yaml:"username"`
	Password string `yaml:"password" secret:"true"`
	Database string `yaml:"database"`
	// TLS is "", true, false, skip-verify or preferred; CACert, when set,
	// verifies the server against that PEM file instead.
	TLS    string `yaml:"tls" validate:"omitempty,oneof=true false skip-verify preferred"`
	CACert string `yaml:"ca_cert"`
}

MySQLConfig is db.mysql. Sessions always run in UTC: the DSN pins parseTime=true and loc=UTC and every connection sets time_zone '+00:00'.

func (MySQLConfig) String added in v0.2.0

func (c MySQLConfig) String() string

String keeps the password out of logs.

type Option added in v0.2.0

type Option func(*openConfig)

Option configures Open.

func Logger added in v0.2.0

func Logger(l *slog.Logger) Option

Logger is where the handle and gorm log; Open captures slog.Default when no logger is supplied. Later Apps cannot redirect an existing handle.

func Migrations added in v0.2.0

func Migrations(fsys fs.FS) Option

Migrations gives the application's SQL files for migrate: versioned, named <14-digit version>_<name>.sql; a sqlite/, mysql/ or postgres/ subdirectory is used for its dialect when present.

func Owner added in v0.2.0

func Owner(name string) Option

Owner names the application's rows in the migration ledger; the default is "app".

func Tables added in v0.2.0

func Tables(specs ...TableSpec) Option

Tables declares the application's tables for migrate: auto.

type OwnedModel

type OwnedModel struct {
	Model
	OwnerID string `json:"-" gorm:"column:owner_id;index;size:128;not null"`
}

OwnedModel is Model whose rows belong to a principal: a store fences every query to the caller's rows and stamps OwnerID on create.

func (*OwnedModel) GetOwnerID added in v0.2.0

func (m *OwnedModel) GetOwnerID() string

GetOwnerID returns the owner.

func (*OwnedModel) SetOwnerID added in v0.2.0

func (m *OwnedModel) SetOwnerID(id string)

SetOwnerID sets the owner.

type OwnedSoftDeleteModel

type OwnedSoftDeleteModel struct {
	SoftDeleteModel
	OwnerID string `json:"-" gorm:"column:owner_id;index;size:128;not null"`
}

OwnedSoftDeleteModel is SoftDeleteModel with an owner.

func (*OwnedSoftDeleteModel) GetOwnerID added in v0.2.0

func (m *OwnedSoftDeleteModel) GetOwnerID() string

GetOwnerID returns the owner.

func (*OwnedSoftDeleteModel) SetOwnerID added in v0.2.0

func (m *OwnedSoftDeleteModel) SetOwnerID(id string)

SetOwnerID sets the owner.

type PoolConfig added in v0.2.0

type PoolConfig struct {
	// MaxOpenConns caps the connections of MySQL and Postgres, 0 meaning
	// no cap. On a SQLite file it sizes the read pool, beside which one
	// writer connection runs: 1 to 64 as given, while 0 or more than 64,
	// the default 100 among them, becomes max(4, number of CPUs). An
	// in-memory SQLite database is one connection.
	MaxOpenConns    int           `yaml:"max_open_conns" default:"100" validate:"gte=0"`
	MaxIdleConns    int           `yaml:"max_idle_conns" default:"10" validate:"gte=0"`
	ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime" default:"1h" validate:"gte=0"`
	ConnMaxIdleTime time.Duration `yaml:"conn_max_idle_time" default:"10m" validate:"gte=0"`
}

PoolConfig is db.pool.

type PostgresConfig added in v0.2.0

type PostgresConfig struct {
	DSN      string `yaml:"dsn" secret:"true"`
	Host     string `yaml:"host" default:"127.0.0.1"`
	Port     int    `yaml:"port" default:"5432" validate:"gte=0,lte=65535"`
	Username string `yaml:"username"`
	Password string `yaml:"password" secret:"true"`
	Database string `yaml:"database"`
	SSLMode  string `yaml:"ssl_mode" default:"disable" validate:"omitempty,oneof=disable require verify-ca verify-full"`
	CACert   string `yaml:"ca_cert"`
}

PostgresConfig is db.postgres: a DSN, or the discrete fields.

func (PostgresConfig) String added in v0.2.0

func (c PostgresConfig) String() string

String keeps the password and the DSN out of logs.

type RIDPrefixer

type RIDPrefixer interface{ RIDPrefix() string }

RIDPrefixer gives a model's RIDs a prefix: posts as pst_xxx.

type SQLiteConfig added in v0.2.0

type SQLiteConfig struct {
	// Path is the database file, or ":memory:". Driver parameters ride
	// in the query string: app.db?_pragma=busy_timeout(10000).
	Path string `yaml:"path" default:"app.db"`
	// CheckpointInterval truncates the WAL periodically; 0 disables.
	CheckpointInterval time.Duration `yaml:"checkpoint_interval" default:"5m" validate:"gte=0"`
	// OptimizeInterval runs PRAGMA optimize periodically; 0 disables.
	OptimizeInterval time.Duration `yaml:"optimize_interval" default:"1h" validate:"gte=0"`
}

SQLiteConfig is db.sqlite. A file database runs in WAL mode with one writer connection and a separate pool of readers.

type SoftDeleteModel

type SoftDeleteModel struct {
	Model
	DeletedAt   gorm.DeletedAt `json:"-" gorm:"index"`
	DeleteToken string         `json:"-" gorm:"column:delete_token;size:24;not null;default:''"`
}

SoftDeleteModel is Model with soft delete: a deleted row keeps its data, gets DeletedAt, and a random DeleteToken that frees it from the SoftUnique indexes so a live row may reuse the values.

type StorePolicy added in v0.2.0

type StorePolicy struct {
	// RequirePrincipal makes writing an owner-scoped row without a
	// principal in the context fail instead of writing an unowned row.
	RequirePrincipal bool `yaml:"require_principal"`
	// AdminRoles see and write every owner's rows.
	AdminRoles []string `yaml:"admin_roles"`
	// OwnerScope fences models that embed an Owned base to the
	// principal's rows; nil means true.
	OwnerScope *bool `yaml:"owner_scope"`
	// DefaultPageSize pages a list a URL asks for without a size, and a
	// page the code asks for without one; a list the code asks for
	// without pagination is every row.
	DefaultPageSize int `yaml:"default_page_size" default:"20" validate:"gte=0"`
	// MaxPageSize bounds the page a URL asks for; the code's own pages
	// take the size they name.
	MaxPageSize int `yaml:"max_page_size" default:"100" validate:"gte=0"`
}

StorePolicy is the posture a store.Store starts from: db.store in the configuration, or store.Policy for one store.

type TableSpec

type TableSpec struct {
	// contains filtered or unexported fields
}

TableSpec declares a model's table for auto migration.

func Table

func Table(model any, indexes ...Index) TableSpec

Table declares the table of model, a struct or pointer to one that embeds a model base, with its indexes: Unique on any model, SoftUnique on a model with soft delete. It panics when the model is not a model, when a SoftUnique is given to a model without soft delete, or when an index names a column that is missing or nullable: the mistake is in the declaration and surfaces at startup.

In migrate: auto, migrating creates each index unless one of its name exists, and an existing one must be the declared index: on the same table, over the same columns in the same order (delete_token last for a SoftUnique), unique and without a WHERE clause. Otherwise Open, RegisterSchema or Migrate fails with both in the error, rather than drop or rebuild the index. MySQL names indexes per table, SQLite and Postgres per schema: there an index of the name on another table differs too.

Jump to

Keyboard shortcuts

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