Documentation
¶
Overview ¶
Package migration provides a framework for managing software migrations.
Migrations handle breaking changes between versions that require special handling beyond a simple upgrade (e.g., uninstall + reinstall, data migration).
Usage ¶
1. Define a migration by implementing the Migration interface:
type MyMigration struct{}
func (m *MyMigration) ID() string { return "my-feature-v1.0.0" }
func (m *MyMigration) Description() string { return "Add my feature" }
func (m *MyMigration) Applies(mctx *Context) (bool, error) { ... }
func (m *MyMigration) Execute(ctx context.Context, mctx *Context) error { ... }
func (m *MyMigration) Rollback(ctx context.Context, mctx *Context) error { ... }
2. Register migrations at startup (e.g., in root.go init):
migration.Register("block-node", &MyMigration{})
3. Get applicable migrations and execute:
mctx := &migration.Context{Component: "block-node", Data: make(map[string]interface{})}
migrations, _ := migration.GetApplicableMigrations("block-node", mctx)
workflow := migration.MigrationsToWorkflow(migrations, mctx)
Index ¶
Constants ¶
const ( CtxKeyInstalledCLIVersion = "installedCLIVersion" CtxKeyCurrentCLIVersion = "currentCLIVersion" )
Well-known CLI version context keys for startup-scoped migrations.
const ( ScopeStartup = "startup" ScopeBlockNode = "block-node" )
Scope constants for migration registration. Use ScopeStartup for migrations that run at every CLI invocation before any command. Use ScopeBlockNode for migrations that run explicitly during block node upgrade workflows.
const ( CtxKeyInstalledVersion = "installedVersion" CtxKeyTargetVersion = "targetVersion" )
Well-known context keys
Variables ¶
This section is empty.
Functions ¶
func ClearRegistry ¶
func ClearRegistry()
ClearRegistry clears all registered migrations. Useful for testing.
func MigrationsToWorkflow ¶
func MigrationsToWorkflow(migrations []Migration, mctx *Context) *automa.WorkflowBuilder
MigrationsToWorkflow converts a list of migrations into an automa workflow. Each migration becomes a step with execute and rollback handlers. The workflow executes migrations in order with rollback on failure.
Types ¶
type CLIVersionMigration ¶ added in v0.14.0
type CLIVersionMigration struct {
// contains filtered or unexported fields
}
CLIVersionMigration provides a base implementation for CLI-version-boundary startup migrations. Embed this in concrete migrations to get ID(), Description(), and Applies() behaviour that gates on the CLI binary version rather than a deployed chart version.
Concrete migrations must implement Execute() and Rollback() themselves.
func NewCLIVersionMigration ¶ added in v0.14.0
func NewCLIVersionMigration(id, description, minVersion string) CLIVersionMigration
NewCLIVersionMigration creates a new CLI-version-gated startup migration. minVersion is the CLI version boundary — applies when upgrading from < minVersion to >= minVersion.
func (*CLIVersionMigration) Applies ¶ added in v0.14.0
func (v *CLIVersionMigration) Applies(mctx *Context) (bool, error)
Applies returns true if the CLI is upgrading across the version boundary. Returns false when installedCLIVersion is empty (fresh install).
func (*CLIVersionMigration) Description ¶ added in v0.14.0
func (v *CLIVersionMigration) Description() string
func (*CLIVersionMigration) ID ¶ added in v0.14.0
func (v *CLIVersionMigration) ID() string
type Context ¶
type Context struct {
// Component identifies what is being migrated (e.g., "block-node")
Component string
// Logger for migration logging
Logger *zerolog.Logger
// Data holds migration-specific data (versions, managers, etc.)
Data automa.StateBag
}
Context provides context for migration execution.
type Migration ¶
type Migration interface {
// ID returns a unique identifier for this migration.
// Convention: "<feature>-v<version>" (e.g., "verification-storage-v0.26.2")
ID() string
// Description returns a human-readable description of what this migration does.
Description() string
// Applies checks if this migration applies to the given context.
Applies(mctx *Context) (bool, error)
// Execute performs the migration.
Execute(ctx context.Context, mctx *Context) error
// Rollback attempts to undo the migration. Best-effort, may not fully restore.
// Return nil if rollback is not supported or not needed.
Rollback(ctx context.Context, mctx *Context) error
}
Migration represents a single migration that handles a breaking change between versions. Implementations should be stateless - all state should be passed via Context.
type VersionMigration ¶
type VersionMigration struct {
// contains filtered or unexported fields
}
VersionMigration provides a base implementation for version-boundary migrations. Embed this in concrete migrations to get ID(), Description(), and Applies() behavior. Concrete migrations must implement Execute() and Rollback() themselves.
func NewVersionMigration ¶
func NewVersionMigration(id, description, minVersion string) VersionMigration
NewVersionMigration creates a new version-based migration. minVersion is the version boundary - applies when upgrading from < minVersion to >= minVersion.
func (*VersionMigration) Applies ¶
func (v *VersionMigration) Applies(mctx *Context) (bool, error)
Applies returns true if upgrading across the version boundary.
func (*VersionMigration) Description ¶
func (v *VersionMigration) Description() string
func (*VersionMigration) ID ¶
func (v *VersionMigration) ID() string
Source Files