headgatemigrate

Documentation

Overview

Package headgatemigrate provides versioned, embedded schema migrations for headgate's Postgres and MySQL stores.

Historical migration checksums are immutable. Postgres applies each version and its history row transactionally. MySQL DDL auto-commits, so each statement is resumable, a connection-scoped lock serializes callers, and history is recorded only after the resulting schema passes the current manifest.

Index

• Constants
• Variables
• func AppliedMySQL(ctx context.Context, db *sql.DB) (InstallationState, []AppliedMigration, error)
• func AppliedPostgres(ctx context.Context, conn *pgx.Conn) (InstallationState, []AppliedMigration, error)
• func AppliedPostgresInSchema(ctx context.Context, conn *pgx.Conn, schema string) (InstallationState, []AppliedMigration, error)
• func Checksum(migration Migration) string
• func LatestVersion(backend Backend) int
• func MySQLMigrationLockName(namespace, database string) (string, error)
• func ValidateHistory(backend Backend, applied []AppliedMigration) error
• type AppliedMigration
  • func AdoptMySQL(ctx context.Context, db *sql.DB) ([]AppliedMigration, error)
  • func AdoptMySQLWithLockNamespace(ctx context.Context, db *sql.DB, lockNamespace string) ([]AppliedMigration, error)
  • func AdoptPostgres(ctx context.Context, conn *pgx.Conn) ([]AppliedMigration, error)
  • func AdoptPostgresInSchema(ctx context.Context, conn *pgx.Conn, schema string) ([]AppliedMigration, error)
• type Backend
• type Direction
• type HistoryError
  • func (e *HistoryError) Error() string
• type InstallationState
• type Migration
  • func GetMigration(backend Backend, version int) (Migration, bool)
  • func Migrations(backend Backend) []Migration
• type MySQLValidation
  • func ValidateMySQL(ctx context.Context, db *sql.DB) (MySQLValidation, error)
  • func (v MySQLValidation) OK() bool
• type Options
• type PostgresValidation
  • func ValidatePostgres(ctx context.Context, conn *pgx.Conn) (PostgresValidation, error)
  • func ValidatePostgresInSchema(ctx context.Context, conn *pgx.Conn, schema string) (PostgresValidation, error)
  • func (v PostgresValidation) OK() bool
• type Result
  • func MigrateMySQL(ctx context.Context, db *sql.DB, direction Direction, options Options) (Result, error)
  • func MigrateMySQLWithLockNamespace(ctx context.Context, db *sql.DB, direction Direction, options Options, ...) (Result, error)
  • func MigratePostgres(ctx context.Context, conn *pgx.Conn, direction Direction, options Options) (Result, error)
  • func MigratePostgresInSchema(ctx context.Context, conn *pgx.Conn, schema string, direction Direction, ...) (Result, error)
• type SchemaError
  • func (e *SchemaError) Error() string
• type Step
  • func Plan(backend Backend, applied []AppliedMigration, direction Direction, ...) ([]Step, error)

Constants

const DefaultMySQLLockNamespace = "headgate"

DefaultMySQLLockNamespace preserves the lock name used before namespaces were configurable: headgate:migrate:<database>.

Variables

var ErrUnversionedSchema = errors.New("headgate tables exist without migration history; validate and adopt the current schema before migrating")

Functions

func AppliedMySQL

func AppliedMySQL(ctx context.Context, db *sql.DB) (InstallationState, []AppliedMigration, error)

func AppliedPostgres

func AppliedPostgres(ctx context.Context, conn *pgx.Conn) (InstallationState, []AppliedMigration, error)

func AppliedPostgresInSchema

func AppliedPostgresInSchema(
	ctx context.Context,
	conn *pgx.Conn,
	schema string,
) (InstallationState, []AppliedMigration, error)

func Checksum

func Checksum(migration Migration) string

func LatestVersion

func LatestVersion(backend Backend) int

func MySQLMigrationLockName

func MySQLMigrationLockName(namespace, database string) (string, error)

MySQLMigrationLockName builds the connection-scoped migration lock key. Readable names stay backward-compatible; only an overlong database is hashed under a distinct :h: marker to fit MySQL's 64-byte GET_LOCK limit without aliasing a short literal database name.

func ValidateHistory

func ValidateHistory(backend Backend, applied []AppliedMigration) error

Types

type AppliedMigration

type AppliedMigration struct {
	Version     int
	Name        string
	Checksum    string
	AppliedAtMS int64
}

func AdoptMySQL

func AdoptMySQL(ctx context.Context, db *sql.DB) ([]AppliedMigration, error)

func AdoptMySQLWithLockNamespace

func AdoptMySQLWithLockNamespace(
	ctx context.Context,
	db *sql.DB,
	lockNamespace string,
) ([]AppliedMigration, error)

func AdoptPostgres

func AdoptPostgres(ctx context.Context, conn *pgx.Conn) ([]AppliedMigration, error)

func AdoptPostgresInSchema

func AdoptPostgresInSchema(
	ctx context.Context,
	conn *pgx.Conn,
	schema string,
) ([]AppliedMigration, error)

type Backend

type Backend string

const (
	Postgres Backend = "postgres"
	MySQL    Backend = "mysql"
)

type Direction

type Direction string

const (
	Up   Direction = "up"
	Down Direction = "down"
)

type HistoryError

type HistoryError struct{ Message string }

func (*HistoryError) Error

func (e *HistoryError) Error() string

type InstallationState

type InstallationState string

const (
	Empty       InstallationState = "empty"
	Unversioned InstallationState = "unversioned"
	Versioned   InstallationState = "versioned"
)

type Migration

type Migration struct {
	Version    int
	Name       string
	UpSQL      string
	DownSQL    string
	OnlineSafe bool
}

func GetMigration

func GetMigration(backend Backend, version int) (Migration, bool)

func Migrations

func Migrations(backend Backend) []Migration

type MySQLValidation

type MySQLValidation struct {
	State          InstallationState
	CurrentVersion int
	LatestVersion  int
	Applied        []AppliedMigration
	Messages       []string
}

func ValidateMySQL

func ValidateMySQL(ctx context.Context, db *sql.DB) (MySQLValidation, error)

func (MySQLValidation) OK

func (v MySQLValidation) OK() bool

type Options

type Options struct {
	TargetVersion *int
	MaxSteps      *int
	DryRun        bool
}

type PostgresValidation

type PostgresValidation struct {
	State          InstallationState
	CurrentVersion int
	LatestVersion  int
	Applied        []AppliedMigration
	Messages       []string
}

func ValidatePostgres

func ValidatePostgres(ctx context.Context, conn *pgx.Conn) (PostgresValidation, error)

func ValidatePostgresInSchema

func ValidatePostgresInSchema(
	ctx context.Context,
	conn *pgx.Conn,
	schema string,
) (PostgresValidation, error)

func (PostgresValidation) OK

func (v PostgresValidation) OK() bool

type Result

type Result struct {
	DryRun bool
	Steps  []Step
}

func MigrateMySQL

func MigrateMySQL(ctx context.Context, db *sql.DB, direction Direction, options Options) (Result, error)

func MigrateMySQLWithLockNamespace

func MigrateMySQLWithLockNamespace(
	ctx context.Context,
	db *sql.DB,
	direction Direction,
	options Options,
	lockNamespace string,
) (Result, error)

func MigratePostgres

func MigratePostgres(
	ctx context.Context,
	conn *pgx.Conn,
	direction Direction,
	options Options,
) (Result, error)

func MigratePostgresInSchema

func MigratePostgresInSchema(
	ctx context.Context,
	conn *pgx.Conn,
	schema string,
	direction Direction,
	options Options,
) (Result, error)

type SchemaError

type SchemaError struct{ Messages []string }

func (*SchemaError) Error

func (e *SchemaError) Error() string

type Step

type Step struct {
	Direction Direction
	Migration Migration
}

func Plan

func Plan(backend Backend, applied []AppliedMigration, direction Direction, options Options) ([]Step, error)