state

Documentation

Index

• Variables
• func HistoryStatusIndicatesApplied(status string) bool
• type MigrationDetail
• type MigrationExecution
• type MigrationFilters
• type MigrationListItem
• type MigrationRecord
• type Reindexer
  • func NewReindexer(tracker StateTracker, registry interface{}, interval time.Duration) *Reindexer
  • func (r *Reindexer) Start()
  • func (r *Reindexer) Stop()
• type SkippedMigration
• type StateTracker

Variables

var ErrMigrationAlreadyInProgress = errors.New("migration is already being executed")

ErrMigrationAlreadyInProgress is returned when another process holds the execution lock for the same migration key (migration_id + schema + connection).

Functions

func HistoryStatusIndicatesApplied

func HistoryStatusIndicatesApplied(status string) bool

HistoryStatusIndicatesApplied returns true if a migrations_history status means the migration completed successfully. The tracker maps executor "success" to "applied" when persisting; both must be treated as applied everywhere we interpret history.

Types

type MigrationDetail

type MigrationDetail struct {
	MigrationID            string
	Schema                 string
	Version                string
	Name                   string
	Connection             string
	Backend                string
	UpSQL                  string
	DownSQL                string
	Dependencies           []string
	StructuredDependencies []backends.Dependency
	Status                 string
}

MigrationDetail represents detailed information about a migration from migrations_list

type MigrationExecution

type MigrationExecution struct {
	MigrationID string
	Schema      string
	Version     string
	Connection  string
	Backend     string
	Status      string
	Applied     bool
	AppliedAt   string
	CreatedAt   string
	UpdatedAt   string
}

MigrationExecution represents an execution record in migrations_executions

type MigrationFilters

type MigrationFilters struct {
	Schema     string
	Table      string
	Connection string
	Backend    string
	Status     string
	Version    string
}

MigrationFilters specifies filters for querying migrations

type MigrationListItem

type MigrationListItem struct {
	MigrationID      string
	Schema           string
	Table            string
	Version          string
	Name             string
	Connection       string
	Backend          string
	LastStatus       string // "success", "failed", "pending", "rolled_back"
	LastAppliedAt    string
	LastErrorMessage string
	Applied          bool
}

MigrationListItem represents a migration in the list with its last execution status

type MigrationRecord

type MigrationRecord struct {
	ID               string
	MigrationID      string // Unique ID: {schema}_{connection}_{version}_{name}
	Schema           string
	Table            string
	Version          string
	Connection       string
	Backend          string
	AppliedAt        string
	Status           string // "success", "failed", "pending", "rolled_back"
	ErrorMessage     string
	ExecutedBy       string // User identifier (from auth context)
	ExecutionMethod  string // "manual", "api", "cli", "worker"
	ExecutionContext string // JSON with additional context (job_id, request_id, etc.)
}

MigrationRecord represents a migration execution record in state tracking (moved here to avoid import cycle)

type Reindexer

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

Reindexer handles background reindexing of migrations

func NewReindexer

func NewReindexer(tracker StateTracker, registry interface{}, interval time.Duration) *Reindexer

NewReindexer creates a new reindexer

func (*Reindexer) Start

func (r *Reindexer) Start()

Start starts the background reindexing process

func (*Reindexer) Stop

func (r *Reindexer) Stop()

Stop stops the background reindexing process

type SkippedMigration

type SkippedMigration struct {
	ID               int
	MigrationID      string
	Schema           string
	Version          string
	Connection       string
	Backend          string
	ExecutedBy       string
	ExecutionMethod  string
	ExecutionContext string
	SkippedAt        string
	CreatedAt        string
}

SkippedMigration represents a skipped migration record

type StateTracker

type StateTracker interface {
	// RecordMigration records a migration execution
	RecordMigration(ctx interface{}, migration *MigrationRecord) error

	// GetMigrationHistory retrieves migration history with optional filters
	GetMigrationHistory(ctx interface{}, filters *MigrationFilters) ([]*MigrationRecord, error)

	// GetMigrationList retrieves the list of migrations with their last status
	GetMigrationList(ctx interface{}, filters *MigrationFilters) ([]*MigrationListItem, error)

	// IsMigrationApplied checks if a migration has been successfully applied.
	// This only returns true for migrations with status 'applied', not 'pending'.
	// For concurrency control (checking if a migration is pending or applied),
	// use IsMigrationPendingOrApplied instead.
	IsMigrationApplied(ctx interface{}, migrationID string) (bool, error)

	// IsMigrationPendingOrApplied checks if a migration is pending or applied.
	// For schema-specific IDs, a row in migrations_executions with status pending may indicate
	// an in-flight run. For base IDs, migrations_list "pending" only means registered-not-applied;
	// cross-process exclusion is enforced via WithMigrationExecutionLock.
	IsMigrationPendingOrApplied(ctx interface{}, migrationID string) (bool, error)

	// WithMigrationExecutionLock runs fn while holding an exclusive lock for this migration
	// execution key. If another session holds the lock, returns ErrMigrationAlreadyInProgress.
	WithMigrationExecutionLock(ctx interface{}, migrationID, schema, connection string, fn func() error) error

	// GetLastMigrationVersion gets the last applied version for a schema/table
	GetLastMigrationVersion(ctx interface{}, schema, table string) (string, error)

	// RegisterScannedMigration registers a scanned migration in migrations_list (status: pending)
	RegisterScannedMigration(ctx interface{}, migrationID, schema, table, version, name, connection, backend string) error

	// UpdateMigrationInfo updates migration metadata (schema, version, name, connection, backend) without affecting status/history
	UpdateMigrationInfo(ctx interface{}, migrationID, schema, table, version, name, connection, backend string) error

	// DeleteMigration deletes a migration from migrations_list (cascades to history via foreign key)
	DeleteMigration(ctx interface{}, migrationID string) error

	// Initialize sets up the state tracking tables
	Initialize(ctx interface{}) error

	// ReindexMigrations reloads the BfM migration list and updates the database state
	// This should be called asynchronously in the background
	ReindexMigrations(ctx interface{}, registry interface{}) error

	// GetMigrationDetail retrieves detailed information about a single migration from migrations_list
	GetMigrationDetail(ctx interface{}, migrationID string) (*MigrationDetail, error)

	// GetMigrationExecutions retrieves all execution records for a migration, ordered by created_at DESC
	GetMigrationExecutions(ctx interface{}, migrationID string) ([]*MigrationExecution, error)

	// GetRecentExecutions retrieves recent execution records across all migrations, ordered by created_at DESC
	GetRecentExecutions(ctx interface{}, limit int) ([]*MigrationExecution, error)

	// RecordSkippedMigrations records skipped migrations for a given execution context
	RecordSkippedMigrations(ctx interface{}, skippedMigrationIDs []string, executedBy, executionMethod, executionContext string) error

	// GetSkippedMigrations retrieves skipped migrations, optionally filtered by migration_id or recent limit
	GetSkippedMigrations(ctx interface{}, migrationID string, limit int) ([]*SkippedMigration, error)

	// RecordDependencyMigration records a dependency migration as applied without creating history entries.
	// Dependencies should only be recorded in the execution history of the migration that depends on them.
	RecordDependencyMigration(ctx interface{}, migration *MigrationRecord) error
}

StateTracker manages migration state tracking