coordinator

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 23, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package coordinator provides a unified interface over the SQL and Redis migration subsystems so callers (CLI, startup checks) can work with "migrations" as a single concept instead of two separate systems.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplyOptions

type ApplyOptions struct {
	// SQLOnly skips Redis migrations.
	SQLOnly bool
	// RedisOnly skips SQL migrations.
	RedisOnly bool
}

ApplyOptions controls an Apply invocation.

type Config

type Config struct {
	SQLMigrator     *migrator.Migrator
	RedisClient     redis.Client
	RedisMigrations []migratorredis.Migration
	DeploymentID    string
	Logger          *logging.Logger
}

Config bundles the inputs needed to construct a Coordinator. Callers are expected to own the lifecycle of the SQL migrator and the Redis client and close them when finished.

type Coordinator

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

Coordinator unifies the SQL and Redis migration subsystems behind a single API. It is intentionally safe to use from both a CLI and from app startup checks.

func New

func New(cfg Config) *Coordinator

New constructs a Coordinator. Either SQLMigrator or the Redis fields may be nil if a subsystem is not configured, but at least one must be provided for any operation to do meaningful work.

func (*Coordinator) Apply

func (c *Coordinator) Apply(ctx context.Context, opts ApplyOptions) error

Apply runs SQL migrations first (if any pending) then Redis migrations in version order. It acquires the Redis distributed lock for the Redis phase to prevent concurrent runs.

func (*Coordinator) List

func (c *Coordinator) List(ctx context.Context) ([]MigrationInfo, error)

List returns the unified view of every migration (SQL + Redis) with its current status.

func (*Coordinator) PendingSummary

func (c *Coordinator) PendingSummary(ctx context.Context) (PendingSummary, error)

PendingSummary returns a lightweight count of pending migrations. Used by the app startup gate (Phase 4) to decide whether to refuse starting the server.

func (*Coordinator) Plan

func (c *Coordinator) Plan(ctx context.Context) (*Plan, error)

Plan returns the aggregated plan describing what Apply would do. It is safe to call with no side effects.

func (*Coordinator) Unlock

func (c *Coordinator) Unlock(ctx context.Context) error

Unlock force-clears the Redis migration lock. SQL migrations use PostgreSQL advisory locks which release automatically when the connection closes, so there is no SQL-side unlock operation.

func (*Coordinator) Verify

func (c *Coordinator) Verify(ctx context.Context) (*VerificationReport, error)

Verify runs verification across both subsystems. For SQL, it checks that the current schema version matches the latest available version. For Redis, it runs each applied migration's Verify method.

type MigrationInfo

type MigrationInfo struct {
	// ID is a stable identifier used for output/reference, e.g.
	// "sql/000003" or "redis/001_hash_tags".
	ID string

	// Type indicates which subsystem owns this migration.
	Type MigrationType

	// Version orders migrations within a given Type.
	Version int

	// Name is a human-readable name (e.g. "init", "hash_tags").
	Name string

	// Description is a longer human-readable explanation. May be empty
	// for SQL migrations (which only have names).
	Description string

	// Status reflects the current state as tracked by the underlying
	// subsystem.
	Status MigrationStatus

	// Reason is populated when Status is StatusNotApplicable.
	Reason string
}

MigrationInfo is the unified view of a single migration across both SQL and Redis subsystems.

type MigrationStatus

type MigrationStatus string

MigrationStatus is the lifecycle state of a single migration.

const (
	StatusPending       MigrationStatus = "pending"
	StatusApplied       MigrationStatus = "applied"
	StatusNotApplicable MigrationStatus = "not_applicable"
)

type MigrationType

type MigrationType string

MigrationType identifies the storage backend a migration targets.

const (
	MigrationTypeSQL   MigrationType = "sql"
	MigrationTypeRedis MigrationType = "redis"
)

type PendingSummary

type PendingSummary struct {
	SQLPending   int
	RedisPending int
}

PendingSummary is a lightweight view used by the startup gate.

func (PendingSummary) HasPending

func (p PendingSummary) HasPending() bool

HasPending returns true if any migrations are pending across subsystems.

type Plan

type Plan struct {
	// SQL summarizes pending SQL migrations.
	SQL SQLPlan
	// Redis lists pending Redis migrations that are applicable.
	Redis []RedisMigrationPlan
}

Plan is the aggregated view of what Apply would do right now.

func (*Plan) HasChanges

func (p *Plan) HasChanges() bool

HasChanges returns true if applying the plan would do anything.

type RedisMigrationPlan

type RedisMigrationPlan struct {
	Name           string
	Description    string
	EstimatedItems int
	Scope          map[string]int
}

RedisMigrationPlan is the plan output for a single Redis migration.

type RedisVerifyResult

type RedisVerifyResult struct {
	Name         string
	Valid        bool
	ChecksRun    int
	ChecksPassed int
	Issues       []string
	VerifiedAt   time.Time
}

RedisVerifyResult captures the outcome of verifying a single Redis migration.

type SQLMigrationInfo

type SQLMigrationInfo struct {
	Version int
	Name    string
}

SQLMigrationInfo is a single SQL migration that is pending.

type SQLPlan

type SQLPlan struct {
	CurrentVersion int
	LatestVersion  int
	PendingCount   int
	Pending        []SQLMigrationInfo
}

SQLPlan summarizes what would happen in the SQL subsystem.

type VerificationReport

type VerificationReport struct {
	SQLCurrentVersion int
	SQLLatestVersion  int
	RedisResults      []RedisVerifyResult
}

VerificationReport is the result of a Verify invocation.

func (*VerificationReport) Ok

func (r *VerificationReport) Ok() bool

Ok returns true if no issues were reported.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL