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
- 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 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) 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) 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) Date(name string) *Column
- func (t *Table) Decimal(name string, precision, scale int) *Column
- 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)
- 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)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ("user_id" → "users").
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 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.
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) 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) UniqueIndex ¶
UniqueIndex adds a unique index over cols.
Source Files