README
¶
Status
The status package provides state management, progress reporting, and periodic task monitoring for Spirit migrations. It defines the lifecycle states that a migration passes through and the infrastructure for background checkpointing and status logging.
State Machine
State is an int32 enum representing the current phase of a migration. It uses atomic.LoadInt32/atomic.StoreInt32 for lock-free concurrent access, since the migration runner and watcher goroutines read and write the state simultaneously.
The states are defined in lifecycle order:
Initial → CopyRows → WaitingOnSentinelTable → ApplyChangeset → RestoreSecondaryIndexes → AnalyzeTable → Checksum → PostChecksum → CutOver → Close → ErrCleanup
This ordering is deliberate — the code uses ordinal comparisons (e.g., state >= CutOver) to determine when to stop checkpointing and status reporting.
Task Interface
The Task interface defines the contract that a migration runner must implement: reporting progress, returning a status string, dumping checkpoints, and cancelling. Both the migration.Runner and move.Runner implement this interface.
Background Monitoring
WatchTask launches two background goroutines:
- Status logger: Logs
task.Status()every 30 seconds until the migration reaches cutover. This provides a regular heartbeat in the logs. - Checkpoint dumper: Calls
task.DumpCheckpoint()every 50 seconds until cutover. If a checkpoint write fails (with anything other thanErrWatermarkNotReadyorcontext.Canceled), the task is cancelled immediately. The rationale is that it is better to fail early than to discover after a multi-day migration that progress was never being saved.
The checkpoint dumper also handles a race condition where the state transitions past cutover mid-checkpoint — the checkpoint table may have already been dropped, so this case is handled gracefully rather than treated as an error.
Progress Reporting
Progress is a struct (not just a string) containing the current state and a summary. It is designed as a struct specifically to allow future expansion for GUI wrappers and external tooling.
See Also
- pkg/migration - Migration runner that implements the
Taskinterface - pkg/move - Move runner that implements the
Taskinterface
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrMismatchedAlter = errors.New("alter statement in checkpoint table does not match the alter statement specified here") ErrBinlogNotFound = errors.New("checkpoint binlog file not found on server") ErrCheckpointTooOld = errors.New("checkpoint is too old to safely resume") ErrCheckpointCollision = errors.New("checkpoint belongs to a different table (truncation collision)") ErrCouldNotWriteCheckpoint = errors.New("could not write checkpoint") ErrWatermarkNotReady = errors.New("watermark not ready") )
var ( CheckpointDumpInterval = 50 * time.Second StatusInterval = 30 * time.Second )
Functions ¶
func WatchTask ¶
WatchTask periodically does the status reporting for a task. This includes writing to the logger the current state, and dumping checkpoints.
It returns a wait function the caller can invoke during shutdown to block until the spawned goroutines have exited. This avoids races where a still-running checkpoint goroutine writes a fresh row after the caller has closed/torn down the surrounding state — a pattern that has produced flakes in tests that mutate the checkpoint table after Run() returns (see #773).
Types ¶
type Progress ¶
type Progress struct {
CurrentState State // current state, i.e. CopyRows
Summary string // text based representation, i.e. "12.5% copyRows ETA 1h 30m"
// Tables contains per-table progress for multi-table migrations.
// For single-table migrations, this will have one entry.
Tables []TableProgress
}
Progress is returned as a struct because we may add more to it later. It is designed for wrappers (like a GUI) to be able to summarize the current status without parsing log output.
type State ¶
type State int32
const ( Initial State = iota CopyRows ApplyChangeset // first mass apply RestoreSecondaryIndexes AnalyzeTable Checksum PostChecksum // second mass apply // WaitingOnSentinelTable comes after the initial checksum so that // `state >= Checksum` is true while the sentinel-wait blocks the cutover. // During this state Spirit also runs the "continuous checksum" loop // described in docs/migrate.md. WaitingOnSentinelTable CutOver Close ErrCleanup )
type TableProgress ¶ added in v0.11.0
type TableProgress struct {
TableName string // name of the table being migrated
RowsCopied uint64 // rows copied so far
RowsTotal uint64 // total rows expected
IsComplete bool // true if this table's copy is complete
}
TableProgress tracks progress for a single table in the migration.
Source Files