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 ( 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 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