migrations

Documentation

Overview

Package migrations reads database schemas and converts them into ddl builders.

The first implementation targets PostgreSQL introspection. It returns a normalized Schema that preserves enough metadata for later diffing and can also be converted into ddl.Statements for rendering.

Index

• Constants
• func GenerateMigrationsConfig(args []string) error
• func MakeMigration(ctx context.Context, comment, outDir string, config *MigrationToolConfig) (string, error)
• func RegisterTable[T qrafter.TableConfigProvider](schema *Schema, d dialect.Renderer)
• func RunMigrationsCommand(args []string) error
• type Column
• type Constraint
• type ConstraintKind
• type Database
• type Index
• type IndexKey
• type Introspector
• type Migration
  • func New(version string, up, down func() ddl.Statements) Migration
• type MigrationApplyConfig
• type MigrationApplyResult
  • func ApplyMigrations(ctx context.Context, config *MigrationApplyConfig) (*MigrationApplyResult, error)
• type MigrationDirection
• type MigrationToolConfig
• type PostgreSQL
  • func NewPostgreSQL(opts ...PostgreSQLOption) PostgreSQL
  • func (p PostgreSQL) ReadSchema(ctx context.Context, db Database) (Schema, error)
• type PostgreSQLOption
  • func WithAllSchemas() PostgreSQLOption
  • func WithSchemas(schemas ...string) PostgreSQLOption
• type Reference
• type Schema
• type Table

Constants

const (
	// DefaultMigrationVersionTable is used to store the current migration version.
	DefaultMigrationVersionTable = "qrafter_schema_version"
)

Functions

func GenerateMigrationsConfig

func GenerateMigrationsConfig(args []string) error

GenerateMigrationsConfig creates the user-editable qrafter migration config.

func MakeMigration

func MakeMigration(ctx context.Context, comment, outDir string, config *MigrationToolConfig) (string, error)

MakeMigration generates a migration file and returns its path.

func RegisterTable

func RegisterTable[T qrafter.TableConfigProvider](schema *Schema, d dialect.Renderer)

RegisterTable appends the schema inferred from table config T to schema.

func RunMigrationsCommand

func RunMigrationsCommand(args []string) error

RunMigrationsCommand dispatches qrafter migration CLI subcommands.

Types

type Column

type Column struct {
	Schema    string
	TableName string
	Position  int
	Name      string
	Type      ddl.Type

	// DatabaseType is the type name returned by database introspection.
	DatabaseType string

	NotNull bool

	HasDefault  bool
	DefaultExpr string

	Identity ddl.IdentityKind

	Generated     ddl.GeneratedKind
	GeneratedExpr string
}

Column describes a table column.

type Constraint

type Constraint struct {
	Schema    string
	TableName string
	Name      string
	Kind      ConstraintKind
	Columns   []string

	CheckExpr string

	Reference Reference
	OnDelete  ddl.ReferenceAction
	OnUpdate  ddl.ReferenceAction
}

Constraint describes a table-level constraint.

type ConstraintKind

type ConstraintKind string

ConstraintKind describes a table-level constraint type.

const (
	// ConstraintPrimaryKey is a PRIMARY KEY constraint.
	ConstraintPrimaryKey ConstraintKind = "primary_key"
	// ConstraintUnique is a UNIQUE constraint.
	ConstraintUnique ConstraintKind = "unique"
	// ConstraintCheck is a CHECK constraint.
	ConstraintCheck ConstraintKind = "check"
	// ConstraintForeignKey is a FOREIGN KEY constraint.
	ConstraintForeignKey ConstraintKind = "foreign_key"
)

type Database

type Database interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Database is implemented by *sql.DB, *sql.Tx, and *sql.Conn.

type Index

type Index struct {
	Schema      string
	TableSchema string
	TableName   string
	Name        string

	Unique bool
	Method ddl.IndexMethod

	Keys    []IndexKey
	Include []string

	Predicate string

	Tablespace       string
	NullsNotDistinct bool
}

Index describes a non-constraint index.

type IndexKey

type IndexKey struct {
	Expression string
}

IndexKey describes one PostgreSQL index key expression.

type Introspector

type Introspector interface {
	ReadSchema(ctx context.Context, db Database) (Schema, error)
}

Introspector reads a database schema into a normalized Schema snapshot.

type Migration

type Migration struct {
	Version string
	Up      func() ddl.Statements
	Down    func() ddl.Statements
}

Migration registers one generated migration version and its up/down DDL.

func New

func New(version string, up, down func() ddl.Statements) Migration

New creates a migration registry entry.

type MigrationApplyConfig

type MigrationApplyConfig struct {
	DB migrationApplyDatabase

	DriverName     string
	DataSourceName string

	Dialect            dialect.Renderer
	Registry           []Migration
	Direction          MigrationDirection
	Target             string
	VersionTable       string
	DisableTransaction bool
}

MigrationApplyConfig configures registered migration execution.

type MigrationApplyResult

type MigrationApplyResult struct {
	Direction MigrationDirection
	From      string
	To        string
	Applied   []string
}

MigrationApplyResult describes migration versions executed by ApplyMigrations.

func ApplyMigrations

func ApplyMigrations(ctx context.Context, config *MigrationApplyConfig) (*MigrationApplyResult, error)

ApplyMigrations applies registered migrations in the requested direction up to target.

type MigrationDirection

type MigrationDirection string

MigrationDirection selects whether registered migrations are applied or reverted.

const (
	// DirectionUp applies migrations forward.
	DirectionUp MigrationDirection = "up"
	// DirectionDown reverts migrations backward.
	DirectionDown MigrationDirection = "down"
)

type MigrationToolConfig

type MigrationToolConfig struct {
	DB Database

	DriverName     string
	DataSourceName string

	Introspector Introspector
	Dialect      dialect.Renderer
	Desired      func(dialect.Renderer) Schema
	VersionTable string
}

MigrationToolConfig configures database schema reading and migration code generation.

type PostgreSQL

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

PostgreSQL reads schema metadata from PostgreSQL.

func NewPostgreSQL

func NewPostgreSQL(opts ...PostgreSQLOption) PostgreSQL

NewPostgreSQL creates a PostgreSQL schema introspector.

func (PostgreSQL) ReadSchema

func (p PostgreSQL) ReadSchema(ctx context.Context, db Database) (Schema, error)

ReadSchema reads a PostgreSQL database schema.

type PostgreSQLOption

type PostgreSQLOption func(*postgreSQLOptions)

PostgreSQLOption configures PostgreSQL schema introspection.

func WithAllSchemas

func WithAllSchemas() PostgreSQLOption

WithAllSchemas introspects all non-system PostgreSQL schemas.

func WithSchemas

func WithSchemas(schemas ...string) PostgreSQLOption

WithSchemas limits introspection to the given schemas. The default is public.

type Reference

type Reference struct {
	Schema    string
	TableName string
	Columns   []string
}

Reference describes a foreign-key target.

type Schema

type Schema struct {
	Tables []Table
}

Schema is a normalized database schema snapshot.

type Table

type Table struct {
	Schema      string
	Name        string
	Columns     []Column
	Constraints []Constraint
	Indexes     []Index
}

Table describes a database table.