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 ¶
- Variables
- func NewRID(prefix string) string
- func ParseRID(rid string) (prefix string, ok bool)
- type Config
- type DB
- func (d *DB) AfterCommit(ctx context.Context, fn func(ctx context.Context)) bool
- func (d *DB) Close(ctx context.Context) error
- func (d *DB) Health(ctx context.Context) error
- func (d *DB) InTx(ctx context.Context) bool
- func (d *DB) Logger() *slog.Logger
- func (d *DB) MarkApplied(ctx context.Context, version string) error
- func (d *DB) Migrate(ctx context.Context) error
- func (d *DB) MigrationStatus(ctx context.Context) ([]MigrationStatus, error)
- func (d *DB) Name() string
- func (d *DB) RegisterSchema(owner string, tables []TableSpec, migrations fs.FS) error
- func (d *DB) RunInTx(ctx context.Context, fn func(txCtx context.Context) error) error
- func (d *DB) StorePolicy() StorePolicy
- func (d *DB) Unsafe(ctx context.Context) *gorm.DB
- type Index
- type MigrationStatus
- type Model
- type Modeler
- type MySQLConfig
- type Option
- type OwnedModel
- type OwnedSoftDeleteModel
- type PoolConfig
- type PostgresConfig
- type RIDPrefixer
- type SQLiteConfig
- type SoftDeleteModel
- type StorePolicy
- type TableSpec
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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
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
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.
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 Open ¶ added in v0.2.0
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
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
Close stops the SQLite maintenance, running a last PRAGMA optimize when ctx allows, and closes the pools.
func (*DB) MarkApplied ¶ added in v0.2.0
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
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) RegisterSchema ¶ added in v0.2.0
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
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
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 ¶
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
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.
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
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
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.
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 ¶
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.