Documentation
¶
Overview ¶
Package schema builds DDL with a fluent, dialect-aware API (SQLite, PostgreSQL and MySQL/MariaDB) and runs versioned migrations with batches and checksums.
s.Create("users", func(t *schema.Table) {
t.ID()
t.String("email").Unique()
t.Timestamps()
})
A Schema builds and runs DDL on any database.Executor. A Migration pairs Up and Down functions under a sortable ID; a Migrator applies them (Up, Rollback, Reset, Fresh, Status) and is what vukem migrate runs. Apps pass their migrations with vukem.WithMigrations.
See https://github.com/AlexGalhardo/vukem/blob/main/docs/database.md#migrations.
Index ¶
- func DropAll(ctx context.Context, db *database.DB) error
- func Record(d database.Dialect, up func(s *Schema) error) ([]string, error)
- type Column
- func (c *Column) CascadeOnDelete() *Column
- func (c *Column) Constrained(table ...string) *Column
- func (c *Column) Default(v any) *Column
- func (c *Column) Index() *Column
- func (c *Column) NullOnDelete() *Column
- func (c *Column) Nullable() *Column
- func (c *Column) RestrictOnDelete() *Column
- func (c *Column) Unique() *Column
- type Expr
- type Index
- type Migration
- type Migrator
- func (m *Migrator) Checksum(mig Migration) (string, error)
- func (m *Migrator) Fresh(ctx context.Context) ([]string, error)
- func (m *Migrator) Reset(ctx context.Context) ([]string, error)
- func (m *Migrator) Rollback(ctx context.Context, steps int) ([]string, error)
- func (m *Migrator) Status(ctx context.Context) ([]Status, error)
- func (m *Migrator) Up(ctx context.Context) ([]string, error)
- type Schema
- func (s *Schema) Create(table string, fn func(t *Table)) error
- func (s *Schema) Dialect() string
- func (s *Schema) Drop(table string) error
- func (s *Schema) DropIfExists(table string) error
- func (s *Schema) HasColumn(table, column string) (bool, error)
- func (s *Schema) HasTable(table string) (bool, error)
- func (s *Schema) Raw(sql string, args ...any) error
- func (s *Schema) Rename(from, to string) error
- func (s *Schema) SQLDialect() database.Dialect
- func (s *Schema) Table(table string, fn func(t *Table)) error
- type Status
- type Table
- func (t *Table) BigInteger(name string) *Column
- func (t *Table) Binary(name string) *Column
- func (t *Table) Boolean(name string) *Column
- func (t *Table) Check(name, expr string)
- func (t *Table) Date(name string) *Column
- func (t *Table) Decimal(name string, precision, scale int) *Column
- func (t *Table) DropCheck(name string)
- func (t *Table) DropColumn(names ...string)
- func (t *Table) DropIndex(name string)
- func (t *Table) Enum(name string, values ...string) *Column
- func (t *Table) Float(name string) *Column
- func (t *Table) ForeignID(name string) *Column
- func (t *Table) ID() *Column
- func (t *Table) Index(cols ...string) *Index
- func (t *Table) Integer(name string) *Column
- func (t *Table) JSON(name string) *Column
- func (t *Table) RenameColumn(from, to string)
- func (t *Table) SoftDeletes() *Column
- func (t *Table) String(name string, length ...int) *Column
- func (t *Table) Text(name string) *Column
- func (t *Table) Timestamp(name string) *Column
- func (t *Table) Timestamps()
- func (t *Table) ULID(name string) *Column
- func (t *Table) UUID(name string) *Column
- func (t *Table) UniqueIndex(cols ...string) *Index
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Record ¶ added in v0.29.0
Record returns the statements up generates for dialect d without running them: the SQL Migrator.Checksum hashes, so a migration can be reviewed or diffed against DDL written elsewhere. Queries are not run while recording, so Schema.HasTable and Schema.HasColumn report false and up records the statements for an empty database.
Types ¶
type Column ¶
type Column struct {
// contains filtered or unexported fields
}
Column is a column definition; modifiers chain.
func (*Column) CascadeOnDelete ¶
CascadeOnDelete deletes children when the parent row is deleted.
func (*Column) Constrained ¶
Constrained adds a foreign key to table(id); the table defaults to the column name without "_id" pluralised with the ORM's table naming ("user_id" → "users", "category_id" → "categories").
func (*Column) NullOnDelete ¶
NullOnDelete sets the column to NULL when the parent row is deleted.
func (*Column) RestrictOnDelete ¶
RestrictOnDelete prevents deleting a referenced parent.
type Index ¶ added in v0.25.0
type Index struct {
// contains filtered or unexported fields
}
Index is an index added by Table.Index or Table.UniqueIndex; chain Where to make it partial.
func (*Index) Where ¶ added in v0.25.0
Where makes the index partial: only rows matching expr are indexed (and, for a unique index, must be unique), e.g. one live reservation per number with UniqueIndex("number_id").Where("status = 'live'"). expr is raw SQL written by the developer (never user input). PostgreSQL and SQLite support it; MySQL and MariaDB have no partial indexes, so the migration fails instead of creating a full index that would reject valid rows.
type Migration ¶
Migration is one versioned schema change. IDs sort chronologically: "20261016120000_create_users_table".
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator applies migrations to a database.
Example ¶
package main
import (
"context"
"fmt"
"github.com/AlexGalhardo/vukem/database"
"github.com/AlexGalhardo/vukem/schema"
)
func main() {
ctx := context.Background()
db, _ := database.Open(ctx, ":memory:")
defer db.Close()
migrations := []schema.Migration{{
ID: "20261016120000_create_users_table",
Up: func(s *schema.Schema) error {
return s.Create("users", func(t *schema.Table) {
t.ID()
t.String("email").Unique()
t.Timestamps()
})
},
Down: func(s *schema.Schema) error { return s.Drop("users") },
}}
m, err := schema.NewMigrator(db, migrations)
if err != nil {
fmt.Println(err)
return
}
ran, _ := m.Up(ctx)
fmt.Println("ran:", ran)
has, _ := schema.New(ctx, db).HasTable("users")
fmt.Println("users table:", has)
rolled, _ := m.Rollback(ctx, 1)
fmt.Println("rolled back:", rolled)
}
Output: ran: [20261016120000_create_users_table] users table: true rolled back: [20261016120000_create_users_table]
func NewMigrator ¶
NewMigrator validates migrations (unique, non-empty IDs, Up present) and sorts them by ID.
func (*Migrator) Checksum ¶
Checksum returns the SHA-256 of the SQL a migration's Up generates for the database's dialect.
func (*Migrator) Fresh ¶
Fresh drops every table and runs all migrations. It is destructive: the CLI requires --force in production.
func (*Migrator) Rollback ¶
Rollback reverts the last batch, or the last steps migrations when steps > 0. It returns the IDs that were reverted, newest first.
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema runs DDL on an executor. In recording mode (used for checksums) statements are collected instead of executed.
func (*Schema) DropIfExists ¶
DropIfExists drops table when it exists.
func (*Schema) HasColumn ¶ added in v0.26.0
HasColumn reports whether table has column (false while recording, and for a missing table), so an upgrade migration can add a column only to tables created before it existed.
func (*Schema) Raw ¶
Raw runs any SQL statement (data migrations, views, triggers). With args, "?" placeholders are rebound to the dialect (database.RebindChecked), so the same data migration runs on SQLite, MySQL and PostgreSQL; a query mixing "?" with "$n" or ending inside a literal is an error. Without args the statement runs as written, so PostgreSQL's jsonb "?" operators in DDL keep working. The migration checksum covers the query as written.
func (*Schema) SQLDialect ¶ added in v0.29.0
SQLDialect returns the dialect the Schema builds DDL for, so a package can render one set of statements for both a migration and a non-migration path, such as a store's boot-time CREATE TABLE IF NOT EXISTS.
type Status ¶
type Status struct {
ID string `json:"id"`
Ran bool `json:"ran"`
Batch int `json:"batch,omitempty"`
RanAt time.Time `json:"ran_at,omitzero"`
Changed bool `json:"changed,omitempty"` // applied migration whose SQL changed since
Missing bool `json:"missing,omitempty"` // recorded in the database but not in code
}
Status describes a migration's state.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table collects column and index definitions for Create or Table.
func (*Table) BigInteger ¶
BigInteger adds a 64-bit integer column.
func (*Table) Check ¶ added in v0.24.0
Check adds a named CHECK constraint. expr is raw SQL written by the developer (never user input); it should only use syntax every target dialect understands. On Create it works on SQLite, PostgreSQL and MySQL. On Table (alter) SQLite cannot add constraints to an existing table, so the migration fails instead of silently skipping the rule. MySQL scopes constraint names per database, so prefix them with the table name.
func (*Table) DropCheck ¶ added in v0.24.0
DropCheck drops a named CHECK constraint (alter only; not supported on SQLite). It emits DROP CONSTRAINT, which needs MySQL 8.0.19+ or MariaDB 10.2+.
func (*Table) DropColumn ¶
DropColumn drops columns (alter only).
func (*Table) ForeignID ¶
ForeignID adds a big integer column meant to reference another table; chain Constrained() to add the foreign key.
func (*Table) RenameColumn ¶
RenameColumn renames a column (alter only).
func (*Table) SoftDeletes ¶
SoftDeletes adds a nullable deleted_at timestamp.
func (*Table) Timestamp ¶
Timestamp adds a timestamp column (TIMESTAMPTZ on PostgreSQL, DATETIME(6) on MySQL).
func (*Table) Timestamps ¶
func (t *Table) Timestamps()
Timestamps adds nullable created_at and updated_at.
func (*Table) ULID ¶
ULID adds a CHAR(26) column, the width of the text form of a ULID. Package ulid generates the values; the Go field is a plain string.
func (*Table) UniqueIndex ¶
UniqueIndex adds a unique index over cols (name derived: table_col1_col2_unique).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package stores ships the migrations for the tables vukem's own database-backed stores use: the queue's jobs and failed jobs tables, the sessions table, the cache table and the webhook delivery log.
|
Package stores ships the migrations for the tables vukem's own database-backed stores use: the queue's jobs and failed jobs tables, the sessions table, the cache table and the webhook delivery log. |