planner

Documentation

Overview

Package planner provides migration planning and strategy generation for schema changes.

Overview

The planner package analyzes schema differences and generates ordered migration plans that respect database constraints and dependencies.

Features

• Dependency resolution (e.g., drop foreign keys before dropping tables)
• Safe operation ordering (e.g., add column before adding constraint)
• Destructive operation detection (data loss warnings)
• Rollback plan generation
• Multi-step migration strategies

Usage

Generate a migration plan:

diffs, _ := comparer.CompareSchemas(oldSchema, newSchema, nil)
plan, err := planner.GeneratePlan(diffs, &planner.Options{
    AllowDestructive: false,
    GenerateRollback: true,
})

for _, step := range plan.Steps {
    fmt.Printf("Step %d: %s\n", step.Order, step.Description)
    if step.Destructive {
        fmt.Println("  WARNING: This step may cause data loss")
    }
}

Migration Strategies

The planner supports different migration strategies:

• Safe: Only non-destructive changes
• Standard: Includes destructive changes with warnings
• Aggressive: Optimizes for speed, may cause downtime

Operation Ordering

The planner ensures operations are executed in the correct order:

1. Drop foreign keys
2. Drop indexes
3. Modify/drop columns
4. Add/modify tables
5. Add columns
6. Add indexes
7. Add foreign keys

Rollback Planning

When enabled, the planner generates rollback steps that can undo non-destructive changes. Destructive operations (DROP TABLE, DROP COLUMN) cannot be automatically rolled back.

Limitations

Current limitations:

• Does not handle data migrations (only DDL)
• Cannot generate rollback for destructive operations
• Does not optimize for minimal downtime

Index

• type MigrationOperation
  • func SortByRisk(ops []*MigrationOperation) []*MigrationOperation
• type MigrationStrategy
  • func AnalyzeStrategy(mdiff *diff.MetadataDiff, eng engine.Engine) (*MigrationStrategy, error)
• type OperationType
• type RiskLevel

Types

type MigrationOperation

type MigrationOperation struct {
	ID           string                  // Unique identifier
	Type         OperationType           // Type of operation
	Action       diff.MetadataDiffAction // CREATE, DROP, or ALTER
	Description  string                  // Human-readable description
	Risk         RiskLevel               // Risk level
	RiskReason   string                  // Explanation of risk
	Dependencies []string                // IDs of operations this depends on
	SQL          string                  // Generated SQL (empty if not generated yet)
	Reversible   bool                    // Whether this operation can be rolled back
	RollbackSQL  string                  // SQL to rollback this operation
	Warnings     []string                // Any warnings about this operation
}

MigrationOperation represents a single DDL operation in the migration.

func SortByRisk

func SortByRisk(ops []*MigrationOperation) []*MigrationOperation

SortByRisk sorts operations by risk level (high to low) for review purposes.

type MigrationStrategy

type MigrationStrategy struct {
	Engine            engine.Engine
	Operations        []*MigrationOperation
	OrderedOperations []*MigrationOperation // Operations in dependency order
	HighRiskOps       []*MigrationOperation // Operations flagged as high risk
	DataLossOps       []*MigrationOperation // Operations that may cause data loss
	Warnings          []string              // Global warnings
}

MigrationStrategy represents the complete migration execution plan.

func AnalyzeStrategy

func AnalyzeStrategy(mdiff *diff.MetadataDiff, eng engine.Engine) (*MigrationStrategy, error)

AnalyzeStrategy analyzes a MetadataDiff and produces a migration strategy.

type OperationType

type OperationType string

OperationType categorizes the type of migration operation.

const (
	OperationTypeSchema     OperationType = "SCHEMA"
	OperationTypeTable      OperationType = "TABLE"
	OperationTypeColumn     OperationType = "COLUMN"
	OperationTypeIndex      OperationType = "INDEX"
	OperationTypeConstraint OperationType = "CONSTRAINT"
	OperationTypeView       OperationType = "VIEW"
	OperationTypeFunction   OperationType = "FUNCTION"
	OperationTypeProcedure  OperationType = "PROCEDURE"
	OperationTypeSequence   OperationType = "SEQUENCE"
	OperationTypeEnum       OperationType = "ENUM"
	OperationTypeEvent      OperationType = "EVENT"
	OperationTypeExtension  OperationType = "EXTENSION"
)

type RiskLevel

type RiskLevel string

RiskLevel represents the risk level of a migration operation.

const (
	RiskLevelNone   RiskLevel = "NONE"   // No risk, fully reversible
	RiskLevelLow    RiskLevel = "LOW"    // Low risk, minor impact
	RiskLevelMedium RiskLevel = "MEDIUM" // Medium risk, requires attention
	RiskLevelHigh   RiskLevel = "HIGH"   // High risk, potential data loss
)