migration

package
v0.31.0 Latest Latest
Warning

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

Go to latest
Published: May 12, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package migration provides integration with Flyway for database migrations

Index

Constants

View Source
const DefaultSecretsPrefix = "gobricks/migrate/"

DefaultSecretsPrefix is the default name prefix used to look up tenant database credentials in a secret store. The full secret name is DefaultSecretsPrefix + tenantID.

Variables

View Source
var ErrEmptyTenantID = errors.New("migration: tenantID is empty")

ErrEmptyTenantID is returned when DBConfig is invoked with a blank tenant ID.

View Source
var ErrInvalidPrefix = errors.New("migration: invalid secrets prefix (must end with '/')")

ErrInvalidPrefix indicates the configured prefix is unusable.

View Source
var ErrNoConfigProvider = errors.New("migration: database.DBConfigProvider is nil")

ErrNoConfigProvider is returned when MigrateAll is called without a DBConfigProvider.

View Source
var ErrNoFetcher = errors.New("migration: SecretsProvider.Fetch is nil")

ErrNoFetcher indicates the SecretsProvider was constructed without a Fetch function.

View Source
var ErrNoLister = errors.New("migration: TenantLister is nil")

ErrNoLister is returned when MigrateAll is called without a TenantLister.

View Source
var ErrSecretMalformed = errors.New("migration: secret payload malformed")

ErrSecretMalformed indicates the secret payload could not be parsed into a usable DatabaseConfig in either canonical or RDS-rotation form.

Functions

This section is empty.

Types

type Action added in v0.31.0

type Action int

Action selects which Flyway operation MigrateAll runs against each tenant.

const (
	// ActionMigrate applies pending migrations.
	ActionMigrate Action = iota
	// ActionValidate verifies migrations without applying them.
	ActionValidate
	// ActionInfo prints the migration status table.
	ActionInfo
)

func (Action) String added in v0.31.0

func (a Action) String() string

String returns the human-readable form of the action.

type Config

type Config struct {
	FlywayPath    string        // Path to the Flyway executable
	ConfigPath    string        // Path to the configuration file
	MigrationPath string        // Path to migration scripts
	Timeout       time.Duration // Timeout for migration operations
	Environment   string        // Environment (development, testing, production)
	DryRun        bool          // Only validate, do not execute
}

Config configuration for migrations

type FlywayMigrator

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

FlywayMigrator handles database migrations using Flyway

func NewFlywayMigrator

func NewFlywayMigrator(cfg *config.Config, log logger.Logger) *FlywayMigrator

NewFlywayMigrator creates a new instance of the migrator

func (*FlywayMigrator) DefaultMigrationConfig added in v0.19.0

func (fm *FlywayMigrator) DefaultMigrationConfig() *Config

DefaultMigrationConfig returns the default configuration for migrations

func (*FlywayMigrator) DefaultMigrationConfigForVendor added in v0.31.0

func (fm *FlywayMigrator) DefaultMigrationConfigForVendor(vendor string) *Config

DefaultMigrationConfigForVendor returns the default migration config for the given database vendor (e.g. "postgresql", "oracle"). Used by multi-tenant migrations where each tenant may run a different vendor than the migrator's own cfg.Database.Type. Unknown vendors fall back to the migrator's configured Database.Type so the vendor string never reaches filesystem path interpolation unvalidated; if even that is unknown, an "unknown" segment is used so callers see an obvious error rather than a path-traversal artifact.

func (*FlywayMigrator) Info

func (fm *FlywayMigrator) Info(ctx context.Context, cfg *Config) error

Info shows information about the status of migrations against the migrator's database.

func (*FlywayMigrator) InfoFor added in v0.31.0

func (fm *FlywayMigrator) InfoFor(ctx context.Context, db *config.DatabaseConfig, cfg *Config) error

InfoFor shows migration status for the supplied database.

func (*FlywayMigrator) Migrate

func (fm *FlywayMigrator) Migrate(ctx context.Context, cfg *Config) error

Migrate executes pending migrations against the migrator's configured database.

func (*FlywayMigrator) MigrateFor added in v0.31.0

func (fm *FlywayMigrator) MigrateFor(ctx context.Context, db *config.DatabaseConfig, cfg *Config) error

MigrateFor executes pending migrations against the supplied database. Used by multi-tenant migrations to target a tenant-specific DatabaseConfig.

func (*FlywayMigrator) RunMigrationsAtStartup

func (fm *FlywayMigrator) RunMigrationsAtStartup(ctx context.Context) error

RunMigrationsAtStartup executes migrations automatically at application startup

func (*FlywayMigrator) Validate

func (fm *FlywayMigrator) Validate(ctx context.Context, cfg *Config) error

Validate validates migrations without executing them against the migrator's database.

func (*FlywayMigrator) ValidateFor added in v0.31.0

func (fm *FlywayMigrator) ValidateFor(ctx context.Context, db *config.DatabaseConfig, cfg *Config) error

ValidateFor validates migrations for the supplied database.

type MigrateAllOptions added in v0.31.0

type MigrateAllOptions struct {
	// BaseConfig supplies Flyway timeout / paths. ConfigPath and
	// MigrationPath are auto-resolved per vendor when zero.
	BaseConfig *Config

	// ContinueOnError keeps iterating after the first per-tenant failure.
	// Default false (fail-fast).
	ContinueOnError bool

	// Parallelism caps concurrent tenant migrations. 0 or 1 = sequential.
	// Implementation caps the value to a reasonable maximum to avoid
	// connection storms.
	Parallelism int

	// Logger receives progress updates. May be nil.
	Logger logger.Logger

	// Hook is invoked after each tenant completes (success or failure).
	// Useful for streaming progress to the CLI / CI logs. May be nil.
	Hook func(TenantResult)
}

MigrateAllOptions tunes per-tenant execution.

type MigrateAllResult added in v0.31.0

type MigrateAllResult struct {
	Action  Action
	Results []TenantResult
}

MigrateAllResult aggregates per-tenant results from a MigrateAll run.

func MigrateAll added in v0.31.0

func MigrateAll(
	ctx context.Context,
	migrator *FlywayMigrator,
	lister TenantLister,
	configs database.DBConfigProvider,
	action Action,
	opts MigrateAllOptions,
) (*MigrateAllResult, error)

MigrateAll lists tenants via lister, resolves each tenant's database config via configs (the existing database.DBConfigProvider abstraction), and runs the chosen Flyway action against every one. Sequential fail-fast unless opts say otherwise.

func (*MigrateAllResult) Failed added in v0.31.0

func (r *MigrateAllResult) Failed() []TenantResult

Failed returns only the tenant results whose Err is non-nil.

type SecretFetcher added in v0.31.0

type SecretFetcher func(ctx context.Context, secretName string) ([]byte, error)

SecretFetcher resolves an opaque secret name to its raw payload bytes. The framework stays decoupled from any specific cloud SDK; callers wire AWS Secrets Manager, HashiCorp Vault, or another store behind this seam.

type SecretsProvider added in v0.31.0

type SecretsProvider struct {
	// Prefix is prepended to each tenant ID when composing the secret name.
	// Empty defaults to DefaultSecretsPrefix at lookup time.
	Prefix string

	// Fetch resolves a secret name to its payload. Required.
	Fetch SecretFetcher
	// contains filtered or unexported fields
}

SecretsProvider implements database.DBConfigProvider on top of a SecretFetcher. It composes the secret name as Prefix + tenantID, fetches the bytes, and parses them as either the canonical go-bricks DatabaseConfig shape or the AWS-managed RDS rotation shape.

func (*SecretsProvider) DBConfig added in v0.31.0

func (p *SecretsProvider) DBConfig(ctx context.Context, tenantID string) (*config.DatabaseConfig, error)

DBConfig satisfies database.DBConfigProvider. Looks up the tenant's secret, parses the payload, and returns the resulting DatabaseConfig.

func (*SecretsProvider) SecretName added in v0.31.0

func (p *SecretsProvider) SecretName(tenantID string) string

SecretName composes the full secret name for the given tenant ID using the provider's prefix (or DefaultSecretsPrefix when unset).

func (*SecretsProvider) Validate added in v0.31.0

func (p *SecretsProvider) Validate() error

Validate checks that the provider is wired correctly. Callers may invoke it eagerly at startup; DBConfig also calls it lazily on first lookup so library callers who skip the explicit check still get a clear error before any tenant fetch.

type TenantLister added in v0.31.0

type TenantLister interface {
	ListTenants(ctx context.Context) ([]string, error)
}

TenantLister enumerates the tenant IDs that should receive migrations. Implementations include the HTTP source (for control-plane APIs) and a static source backed by config.TenantStore.

type TenantResult added in v0.31.0

type TenantResult struct {
	TenantID string
	Vendor   string
	Err      error
	Duration time.Duration
}

TenantResult captures the outcome of running an Action against one tenant.

Directories

Path Synopsis
source
http
Package http provides a TenantLister that pulls tenant IDs from a control-plane API conforming to the go-bricks pre-defined contract.
Package http provides a TenantLister that pulls tenant IDs from a control-plane API conforming to the go-bricks pre-defined contract.
static
Package static provides a TenantLister that enumerates tenant IDs from a config-backed source (typically the YAML-driven multitenant.tenants block).
Package static provides a TenantLister that enumerates tenant IDs from a config-backed source (typically the YAML-driven multitenant.tenants block).

Jump to

Keyboard shortcuts

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