migration

type Migration ¶ added in v0.5.0

type Migration interface {
	// Before restores internal state from a previous migration attempt.
	// Called before each execution of Migrate(), including first-time runs.
	// intermediateState is nil for first-time execution, non-nil when resuming.
	Before(intermediateState []byte) error

	// Migrate executes the migration logic.
	// Returns (intermediateState, error):
	//   - (nil, nil): Migration complete
	//   - (state, nil): Migration in progress, will resume with this state
	//   - (state, error): Error occurred; state is saved if error is context.Canceled
	//   - (nil, error): Error occurred; any existing state is cleared
	Migrate(
		ctx context.Context,
		database db.KeyValueStore,
		network *utils.Network,
		log utils.StructuredLogger,
	) ([]byte, error)
}

Migration represents a migration that can be applied to the database.

Execution Flow:

1. Before(intermediateState) is called to restore state before each execution attempt
2. Migrate() is called to perform the migration work
3. Based on Migrate() return values: - (nil, nil): Migration complete, marked as applied - (state, nil): Migration in progress, state saved for resumption - (state, error): Error occurred; if context.Canceled, state is saved if non-nil

Intermediate State:

• Before() receives intermediateState loaded from the database (nil on first run)
• Migrate() returns intermediateState to allow resumable migrations
• If Migrate() returns non-nil state, it's saved and the migration will resume on next run
• If Migrate() returns nil state, the migration is marked complete and state is cleared
• On cancellation, non-nil state is saved; nil state clears any existing state

This two-phase design separates state restoration from migration work, allowing Migrate() to focus solely on doing the work while Before() handles state management.

type MigrationRunner ¶ added in v0.15.18

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

func NewRunner(
	registry *Registry,
	database db.KeyValueStore,
	network *utils.Network,
	log utils.StructuredLogger,
) (*MigrationRunner, error)

func (mr *MigrationRunner) Run(ctx context.Context) error

type Registry ¶ added in v0.15.18

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

Registry holds all migrations and builds the target version.

func NewRegistry() *Registry

func (r *Registry) Count() int

func (r *Registry) Entries() []Migration

func (r *Registry) OptionalMigrationFlags() []string

func (r *Registry) TargetVersion() SchemaVersion

func (r *Registry) With(m Migration) *Registry

func (r *Registry) WithOptional(m Migration, enabled bool, name string) *Registry

type SchemaMetadata ¶ added in v0.8.0

type SchemaMetadata struct {
	CurrentVersion    SchemaVersion // Applied migrations
	LastTargetVersion SchemaVersion // Previous target (for opt-out prevention)
}

SchemaMetadata tracks the migration state of the database.

CurrentVersion: migrations that have been successfully applied to the database. LastTargetVersion: the target version from the previous migration run. This is used to prevent opt-out: users cannot disable migrations that were previously enabled. When a migration run starts, the current targetVersion is saved here to become the "last target" for the next run.

func GetSchemaMetadata(r db.KeyValueReader) (SchemaMetadata, error)

type SchemaVersion ¶

type SchemaVersion uint64

SchemaVersion represents a schema version as a bitset. It uses a uint64 where each bit at index i represents whether migration i is included. Bits can only be set (never cleared), ensuring migrations are never "unapplied". Supports up to 64 migrations (bits 0-63).

func (sv SchemaVersion) Contains(other SchemaVersion) bool

func (sv SchemaVersion) Difference(other SchemaVersion) SchemaVersion

func (sv SchemaVersion) Has(index uint8) bool

func (sv SchemaVersion) HighestBit() int

func (sv SchemaVersion) Iter() iter.Seq[uint8]

func (sv SchemaVersion) Len() int

func (sv *SchemaVersion) Set(index uint8)

func (sv SchemaVersion) String() string

func (sv SchemaVersion) Union(other SchemaVersion) SchemaVersion