migration

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: May 23, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	WarningMigrationUnsupported           = "MIGRATION_UNSUPPORTED"
	WarningMigrationDropTable             = "MIGRATION_DROP_TABLE"
	WarningMigrationDropColumn            = "MIGRATION_DROP_COLUMN"
	WarningMigrationAddNotNullColumn      = "MIGRATION_ADD_NOT_NULL_COLUMN"
	WarningMigrationRenameColumn          = "MIGRATION_RENAME_COLUMN"
	WarningMigrationAlterColumnType       = "MIGRATION_ALTER_COLUMN_TYPE"
	WarningMigrationTypeNarrowing         = "MIGRATION_TYPE_NARROWING"
	WarningMigrationSetNotNull            = "MIGRATION_SET_NOT_NULL"
	WarningMigrationAddIndexNonConcurrent = "MIGRATION_ADD_INDEX_NON_CONCURRENT"
	WarningMigrationDropIndex             = "MIGRATION_DROP_INDEX"
)

Variables

This section is empty.

Functions

func EnsureExecutable 

func EnsureExecutable(plan *MigrationPlan) error

EnsureExecutable enforces migration approval requirements before execution.

func WriteJSON 

func WriteJSON(w io.Writer, plan *MigrationPlan) error

WriteJSON writes a machine-readable migration plan.

func WritePretty 

func WritePretty(w io.Writer, plan *MigrationPlan) error

WritePretty writes a human-readable migration plan.

Types

type AppliedMigration added in v0.6.0 

type AppliedMigration struct {
	Version   string     `json:"version"`
	AppliedAt *time.Time `json:"applied_at,omitempty"`
	Dirty     bool       `json:"dirty,omitempty"`
}

AppliedMigration is one row read from the migration status table.

type ColumnSchema 

type ColumnSchema struct {
	Name              string `json:"name"`
	Type              string `json:"type,omitempty"`
	Nullable          bool   `json:"nullable"`
	HasDefault        bool   `json:"has_default,omitempty"`
	DefaultExpression string `json:"default_expression,omitempty"`
}

ColumnSchema describes a column in a schema diff.

type Executor 

type Executor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

Executor is the minimal execution surface used by Apply.

type IndexSchema 

type IndexSchema struct {
	Name       string   `json:"name"`
	Columns    []string `json:"columns,omitempty"`
	Unique     bool     `json:"unique,omitempty"`
	Concurrent bool     `json:"concurrent,omitempty"`
}

IndexSchema describes an index in a schema diff.

type MigrationPlan 

type MigrationPlan struct {
	SQL               string                  `json:"sql"`
	Statements        []MigrationStatement    `json:"statements,omitempty"`
	Steps             []MigrationStep         `json:"steps,omitempty"`
	RiskLevel         query.RiskLevel         `json:"risk_level"`
	Warnings          []query.Warning         `json:"warnings,omitempty"`
	RequiredApproval  bool                    `json:"required_approval"`
	Blocked           bool                    `json:"blocked,omitempty"`
	Approval          *query.Approval         `json:"approval,omitempty"`
	AnalysisPrecision query.AnalysisPrecision `json:"analysis_precision"`
	Metadata          map[string]any          `json:"metadata,omitempty"`
}

MigrationPlan explains a schema migration before it is applied.

func DiffSchemas 

func DiffSchemas(current, desired Schema) *MigrationPlan

DiffSchemas creates a migration plan that transforms current into desired.

func PlanSQL 

func PlanSQL(sqlText string) (*MigrationPlan, error)

PlanSQL builds a migration plan from raw migration SQL.

func PlanSteps 

func PlanSteps(steps []MigrationStep) *MigrationPlan

PlanSteps builds a MigrationPlan from structured steps.

func (*MigrationPlan) RequiresApproval 

func (p *MigrationPlan) RequiresApproval() bool

RequiresApproval reports whether this migration needs an explicit approval reason.

func (*MigrationPlan) String 

func (p *MigrationPlan) String() string

String returns a compact human-readable migration summary.

func (*MigrationPlan) ToJSON 

func (p *MigrationPlan) ToJSON() ([]byte, error)

ToJSON returns stable, indented JSON for the migration plan.

type MigrationStatement 

type MigrationStatement struct {
	SQL  string `json:"sql"`
	Line int    `json:"line,omitempty"`
}

MigrationStatement is one executable SQL statement in a migration plan.

type MigrationStep 

type MigrationStep struct {
	Type              MigrationStepType       `json:"type"`
	Table             string                  `json:"table,omitempty"`
	Column            string                  `json:"column,omitempty"`
	FromName          string                  `json:"from_name,omitempty"`
	ToName            string                  `json:"to_name,omitempty"`
	Index             string                  `json:"index,omitempty"`
	ColumnType        string                  `json:"column_type,omitempty"`
	OldType           string                  `json:"old_type,omitempty"`
	NewType           string                  `json:"new_type,omitempty"`
	Nullable          *bool                   `json:"nullable,omitempty"`
	HasDefault        bool                    `json:"has_default,omitempty"`
	DefaultExpression string                  `json:"default_expression,omitempty"`
	Concurrent        bool                    `json:"concurrent,omitempty"`
	SQL               string                  `json:"sql,omitempty"`
	Line              int                     `json:"line,omitempty"`
	RiskLevel         query.RiskLevel         `json:"risk_level"`
	Warnings          []query.Warning         `json:"warnings,omitempty"`
	Preflight         []string                `json:"preflight,omitempty"`
	AnalysisPrecision query.AnalysisPrecision `json:"analysis_precision"`
}

MigrationStep describes one schema change extracted from migration SQL.

type MigrationStepType 

type MigrationStepType string

MigrationStepType classifies a structural schema migration step. 

const (
	AddTable         MigrationStepType = "add_table"
	DropTable        MigrationStepType = "drop_table"
	AddColumn        MigrationStepType = "add_column"
	DropColumn       MigrationStepType = "drop_column"
	RenameColumn     MigrationStepType = "rename_column"
	AlterColumnType  MigrationStepType = "alter_column_type"
	AlterNullability MigrationStepType = "alter_nullability"
	AddIndex         MigrationStepType = "add_index"
	DropIndex        MigrationStepType = "drop_index"
	UnsupportedStep  MigrationStepType = "unsupported"
)

type Migrator 

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

Migrator builds and optionally applies a migration plan.

func New 

func New(sqlText string) *Migrator

New creates a migration planner for SQL text.

func (*Migrator) Apply 

func (m *Migrator) Apply(ctx context.Context, exec Executor) (*MigrationPlan, error)

Apply validates and executes migration statements sequentially.

func (*Migrator) DryRun 

func (m *Migrator) DryRun(ctx context.Context) (*MigrationPlan, error)

DryRun builds and validates the migration plan without executing it.

func (*Migrator) Plan 

func (m *Migrator) Plan(ctx context.Context) (*MigrationPlan, error)

Plan builds a migration plan without executing it.

func (*Migrator) RequireApproval 

func (m *Migrator) RequireApproval(reason string) *Migrator

RequireApproval records an explicit reason for applying a risky migration.

type Schema 

type Schema struct {
	Tables []TableSchema `json:"tables,omitempty"`
}

Schema is a minimal desired/current schema representation for diff planning.

type Status added in v0.6.0 

type Status struct {
	Table         string             `json:"table"`
	Exists        bool               `json:"exists"`
	Applied       []AppliedMigration `json:"applied,omitempty"`
	LatestApplied string             `json:"latest_applied,omitempty"`
	Pending       []string           `json:"pending,omitempty"`
	Dirty         bool               `json:"dirty,omitempty"`
	Unknown       bool               `json:"unknown,omitempty"`
	Warnings      []string           `json:"warnings,omitempty"`
}

Status is a lightweight best-effort view of migration table state.

func ReadStatus added in v0.6.0 

func ReadStatus(ctx context.Context, exec StatusExecutor, dialect driver.Dialect, desired []string, opts ...StatusOption) (Status, error)

ReadStatus reads the migration table state and compares it with desired versions supplied by the caller. It is intended for readiness checks, not as a complete schema drift detector.

type StatusExecutor added in v0.6.0 

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

StatusExecutor is the read surface used by ReadStatus.

type StatusOption added in v0.6.0 

type StatusOption func(*StatusOptions)

StatusOption configures ReadStatus.

func WithStatusAppliedAtColumn added in v0.6.0 

func WithStatusAppliedAtColumn(column string) StatusOption

WithStatusAppliedAtColumn reads an optional applied-at timestamp column.

func WithStatusDirtyColumn added in v0.6.0 

func WithStatusDirtyColumn(column string) StatusOption

WithStatusDirtyColumn enables dirty-state detection from column.

func WithStatusTable added in v0.6.0 

func WithStatusTable(table string) StatusOption

WithStatusTable sets the migration table name. The default is schema_migrations.

func WithStatusVersionColumn added in v0.6.0 

func WithStatusVersionColumn(column string) StatusOption

WithStatusVersionColumn sets the version column. The default is version.

type StatusOptions added in v0.6.0 

type StatusOptions struct {
	Table           string
	VersionColumn   string
	DirtyColumn     string
	AppliedAtColumn string
}

StatusOptions configures the migration status table reader.

type TableSchema 

type TableSchema struct {
	Name    string         `json:"name"`
	Columns []ColumnSchema `json:"columns,omitempty"`
	Indexes []IndexSchema  `json:"indexes,omitempty"`
}

TableSchema describes a table in a schema diff.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.