migration

Documentation

Overview

Package migration coordinates multi-resource data migration lifecycles.

Cutover verification steps are application-supplied hooks — this package never executes arbitrary SQL or opaque scripts. Ownership and fencing are soft hooks so adapters remain honest about what they can enforce.

Index

• Constants
• Variables
• type Checkpoint
• type Config
• type Coordinator
  • func New(cfg Config) *Coordinator
  • func NewCoordinator() *Coordinator
  • func (c *Coordinator) Compensate(name, reason string) (Progress, error)
  • func (c *Coordinator) Define(def Definition) error
  • func (c *Coordinator) DefineSimple(name, source, target string) error
  • func (c *Coordinator) Get(name string) (Run, error)
  • func (c *Coordinator) List() []Progress
  • func (c *Coordinator) Pause(name, reason string) (Progress, error)
  • func (c *Coordinator) ProgressOf(name string) (Progress, error)
  • func (c *Coordinator) ReportCopy(name string, copied, total int64) error
  • func (c *Coordinator) Resume(ctx context.Context, name string) (Progress, error)
  • func (c *Coordinator) SetHooks(h Hooks)
  • func (c *Coordinator) SetPhase(name string, phase Phase) error
  • func (c *Coordinator) Start(ctx context.Context, name string, opts StartOptions) (Progress, error)
• type CutoverHook
• type Definition
• type FenceGate
• type Hooks
• type LockdownGate
• type OwnershipGate
• type Phase
  • func (p Phase) Terminal() bool
• type Progress
• type Run
• type StartOptions
• type VerifyStep

Constants

const DefaultMaxMigrations = 256

DefaultMaxMigrations bounds tracked definitions.

Variables

var (
	ErrNotFound      = errors.New("migration: not found")
	ErrDuplicate     = errors.New("migration: duplicate")
	ErrInvalidPhase  = errors.New("migration: invalid phase transition")
	ErrInvalidArg    = errors.New("migration: invalid argument")
	ErrPaused        = errors.New("migration: paused")
	ErrLockdown      = errors.New("migration: lockdown blocks mutation")
	ErrFence         = errors.New("migration: fencing check failed")
	ErrOwnership     = errors.New("migration: ownership required")
	ErrDryRun        = errors.New("migration: dry-run cannot mutate")
	ErrVerifyFailed  = errors.New("migration: cutover verification failed")
	ErrBoundExceeded = errors.New("migration: bound exceeded")
)

Types

type Checkpoint

type Checkpoint struct {
	Name       string            `json:"name"`
	Phase      Phase             `json:"phase"`
	ResumeFrom Phase             `json:"resume_from,omitempty"`
	Copied     int64             `json:"copied,omitempty"`
	Total      int64             `json:"total,omitempty"`
	Percent    float64           `json:"percent,omitempty"`
	Attrs      map[string]string `json:"attrs,omitempty"`
	UpdatedAt  time.Time         `json:"updated_at"`
}

Checkpoint is a pause/resume snapshot (no secrets).

type Config

type Config struct {
	Hooks         Hooks
	MaxMigrations int
	Clock         func() time.Time
}

Config configures a Coordinator.

type Coordinator

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

Coordinator tracks and advances migrations with ownership/fencing hooks.

func New

func New(cfg Config) *Coordinator

New creates a coordinator with config.

func NewCoordinator

func NewCoordinator() *Coordinator

NewCoordinator creates an empty coordinator.

func (*Coordinator) Compensate

func (c *Coordinator) Compensate(name, reason string) (Progress, error)

Compensate enters compensating then failed (app hooks may extend later).

func (*Coordinator) Define

func (c *Coordinator) Define(def Definition) error

Define registers a migration in planned phase.

func (*Coordinator) DefineSimple

func (c *Coordinator) DefineSimple(name, source, target string) error

DefineSimple registers a migration by name/source/target (planned).

func (*Coordinator) Get

func (c *Coordinator) Get(name string) (Run, error)

Get returns a copy of the run.

func (*Coordinator) List

func (c *Coordinator) List() []Progress

List returns sanitized progress for all runs.

func (*Coordinator) Pause

func (c *Coordinator) Pause(name, reason string) (Progress, error)

Pause checkpoints and enters paused phase.

func (*Coordinator) ProgressOf

func (c *Coordinator) ProgressOf(name string) (Progress, error)

ProgressOf returns sanitized progress.

func (*Coordinator) ReportCopy

func (c *Coordinator) ReportCopy(name string, copied, total int64) error

ReportCopy updates copy progress (sanitized counters only).

func (*Coordinator) Resume

func (c *Coordinator) Resume(ctx context.Context, name string) (Progress, error)

Resume continues from a paused checkpoint.

func (*Coordinator) SetHooks

func (c *Coordinator) SetHooks(h Hooks)

SetHooks updates soft integrations.

func (*Coordinator) SetPhase

func (c *Coordinator) SetPhase(name string, phase Phase) error

SetPhase is a low-level phase update for tests/operators (validates transition).

func (*Coordinator) Start

func (c *Coordinator) Start(ctx context.Context, name string, opts StartOptions) (Progress, error)

Start begins advancing from planned (or resumes from paused checkpoint).

type CutoverHook

type CutoverHook func(ctx context.Context, run *Run) error

CutoverHook runs during cutover (app-owned switch / dual-write flip).

type Definition

type Definition struct {
	Name        string
	Source      string
	Target      string
	Owner       string
	Fence       uint64
	SourceID    resource.ResourceID
	TargetID    resource.ResourceID
	VerifySteps []VerifyStep
	Cutover     CutoverHook
	MaxBytes    int64 // optional budget hint recorded in progress attrs only
}

Definition is a registered migration plan.

type FenceGate

type FenceGate interface {
	CheckFence(resourceID resource.ResourceID, fence uint64) error
}

FenceGate is a soft fencing check.

type Hooks

type Hooks struct {
	Ownership OwnershipGate
	Fence     FenceGate
	Lockdown  LockdownGate
}

Hooks wires soft Runtime/adapter integrations.

type LockdownGate

type LockdownGate interface {
	BlocksMutations() bool
}

LockdownGate blocks mutating phase advances when active.

type OwnershipGate

type OwnershipGate interface {
	Owns(resourceID resource.ResourceID, owner string) bool
}

OwnershipGate is a soft ownership check (e.g. lease held).

type Phase

type Phase string

Phase is a migration lifecycle stage.

const (
	PhasePlanned      Phase = "planned"
	PhaseValidated    Phase = "validated"
	PhasePreparing    Phase = "preparing"
	PhaseCopying      Phase = "copying"
	PhaseVerifying    Phase = "verifying"
	PhaseCutover      Phase = "cutover"
	PhasePaused       Phase = "paused"
	PhaseCompensating Phase = "compensating"
	PhaseCompleted    Phase = "completed"
	PhaseFailed       Phase = "failed"
)

func (Phase) Terminal

func (p Phase) Terminal() bool

Terminal reports whether p is terminal.

type Progress

type Progress struct {
	Name      string    `json:"name"`
	Phase     Phase     `json:"phase"`
	Copied    int64     `json:"copied,omitempty"`
	Total     int64     `json:"total,omitempty"`
	Percent   float64   `json:"percent,omitempty"`
	DryRun    bool      `json:"dry_run,omitempty"`
	Message   string    `json:"message,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

Progress is a sanitized progress view.

type Run

type Run struct {
	Name       string
	Source     string
	Target     string
	Phase      Phase
	DryRun     bool
	Owner      string
	Fence      uint64
	SourceID   resource.ResourceID
	TargetID   resource.ResourceID
	Copied     int64
	Total      int64
	Message    string
	Checkpoint Checkpoint
	UpdatedAt  time.Time
}

Run is a live or paused migration instance.

type StartOptions

type StartOptions struct {
	DryRun bool
	// Total optional expected units for progress percent.
	Total int64
	// CopiedSeed seeds copied counter (resume).
	CopiedSeed int64
	// PauseAfter advances until this phase then pauses (empty = run through).
	PauseAfter Phase
	// contains filtered or unexported fields
}

StartOptions configures Start.

type VerifyStep

type VerifyStep func(ctx context.Context, run *Run) error

VerifyStep is an app-supplied cutover check (no SQL execution here).