queen

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

Queen

Queen

Queen is a Go library for database migrations defined in code. It runs SQL or Go functions, tracks applied versions and checksums, and provides an embeddable CLI for migration jobs. PostgreSQL is the reference production driver; MySQL, SQLite, ClickHouse, CockroachDB, and SQL Server have driver-specific guarantees.

Install

go get github.com/dmedovich/queen

Requires Go 1.26.3 or newer.

Example

package main

import (
    "context"
    "database/sql"
    "log"
    "os"

    "github.com/dmedovich/queen"
    "github.com/dmedovich/queen/drivers/postgres"
    _ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
    db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    q := queen.New(postgres.New(db))
    defer q.Close()
    q.MustAdd(queen.M{
        Version: "001",
        Name: "create_users",
        UpSQL: `CREATE TABLE users (id BIGSERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE)`,
        DownSQL: `DROP TABLE users`,
    })

    if err := q.Up(context.Background()); err != nil {
        log.Fatal(err)
    }
}

For CI/CD, compile your migration registry into a dedicated binary and run it before the application rollout. The quick start and CI/CD guide show the setup.

Documentation

The documentation site covers the API, CLI, PostgreSQL behavior, Goose import, driver guarantees, and release notes. Its source is in website. See the changelog for release changes.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package queen provides a lightweight database migration library for Go.

Example

Example demonstrates basic usage of Queen migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	// Register migrations
	q.MustAdd(queen.M{
		Version: "001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255))`,
		DownSQL: `DROP TABLE users`,
	})

	q.MustAdd(queen.M{
		Version: "002",
		Name:    "add_users_name",
		UpSQL:   `ALTER TABLE users ADD COLUMN name VARCHAR(255)`,
		DownSQL: `ALTER TABLE users DROP COLUMN name`,
	})

	// Apply all pending migrations
	ctx := context.Background()
	if err := q.Up(ctx); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Migrations applied successfully!")
}
Example (Configuration)

Example_configuration demonstrates custom configuration. 

package main

import (
	"context"
	"time"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()

	config := &queen.Config{
		TableName:   "custom_migrations", // Custom table name
		LockTimeout: 30 * time.Minute,
		SkipLock:    false, // Enable lock protection
	}

	q := queen.NewWithConfig(driver, config)
	defer func() { _ = q.Close() }()

	_ = q.Up(context.Background())
}
Example (GoFunctionMigration)

Example_goFunctionMigration demonstrates using Go functions for complex migrations. 

package main

import (
	"context"
	"database/sql"
	"strings"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	// SQL migration to create table
	q.MustAdd(queen.M{
		Version: "001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255))`,
		DownSQL: `DROP TABLE users`,
	})

	// Go function migration for complex data transformation
	q.MustAdd(queen.M{
		Version:        "002",
		Name:           "normalize_emails",
		ManualChecksum: "v1", // Track function changes
		UpFunc: func(ctx context.Context, tx *sql.Tx) error {
			rows, err := tx.QueryContext(ctx, "SELECT id, email FROM users")
			if err != nil {
				return err
			}
			defer func() { _ = rows.Close() }()

			for rows.Next() {
				var id int
				var email string
				if err := rows.Scan(&id, &email); err != nil {
					return err
				}

				normalized := strings.ToLower(strings.TrimSpace(email))

				_, err = tx.ExecContext(ctx,
					"UPDATE users SET email = $1 WHERE id = $2",
					normalized, id)
				if err != nil {
					return err
				}
			}

			return rows.Err()
		},
	})

	_ = q.Up(context.Background())
}
Example (ModularMigrations)

Example_modularMigrations demonstrates organizing migrations by domain. 

package main

import (
	"context"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	// Register migrations from different modules
	registerUserMigrations(q)
	registerPostMigrations(q)

	_ = q.Up(context.Background())
}

func registerUserMigrations(q *queen.Queen) {
	q.MustAdd(queen.M{
		Version: "users_001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id SERIAL PRIMARY KEY)`,
		DownSQL: `DROP TABLE users`,
	})
}

func registerPostMigrations(q *queen.Queen) {
	q.MustAdd(queen.M{
		Version: "posts_001",
		Name:    "create_posts",
		UpSQL:   `CREATE TABLE posts (id SERIAL PRIMARY KEY)`,
		DownSQL: `DROP TABLE posts`,
	})
}
Example (Status)

Example_status demonstrates checking migration status. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	q.MustAdd(queen.M{
		Version: "001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id INT)`,
		DownSQL: `DROP TABLE users`,
	})

	ctx := context.Background()

	// Check status of all migrations
	statuses, err := q.Status(ctx)
	if err != nil {
		log.Fatal(err)
	}

	for _, s := range statuses {
		fmt.Printf("Version: %s, Name: %s, Status: %s\n",
			s.Version, s.Name, s.Status)
	}
}
Example (Testing)

Example_testing demonstrates testing migrations. 

package main

import (
	"testing"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	// In your test
	testFunc := func(t *testing.T) {
		driver := setupTestDB(t) // Your test DB setup

		q := queen.NewTest(t, driver) // Auto-cleanup on test end

		q.MustAdd(queen.M{
			Version: "001",
			Name:    "create_users",
			UpSQL:   `CREATE TABLE users (id INT)`,
			DownSQL: `DROP TABLE users`,
		})

		// Test both up and down migrations
		q.TestUpDown()
	}

	// Run the test (in real code, use go test)
	t := &testing.T{}
	testFunc(t)
}

func setupTestDB(_ *testing.T) queen.Driver {

	return mock.New()
}

Index

Examples

Constants

View Source 
const (

	// RecoveryApplied confirms that an interrupted migration's SQL effects exist.
	RecoveryApplied = "applied"
	// RecoveryNotApplied confirms that an interrupted migration's SQL effects do not exist.
	RecoveryNotApplied = "not-applied"
)
View Source 
const (
	DirectionUp   = "up"
	DirectionDown = "down"
	DriverUnknown = "unknown"
)

Variables

View Source 
var (
	ErrNoMigrations         = errors.New("no migrations registered")
	ErrVersionConflict      = errors.New("version conflict")
	ErrMigrationNotFound    = errors.New("migration not found")
	ErrChecksumMismatch     = errors.New("checksum mismatch")
	ErrLockTimeout          = errors.New("lock timeout")
	ErrNoDriver             = errors.New("driver not initialized")
	ErrInvalidMigration     = errors.New("invalid migration")
	ErrNameTooLong          = errors.New("migration name exceeds 63 characters")
	ErrInvalidMigrationName = errors.New("invalid migration name")
	ErrAlreadyApplied       = errors.New("migration already applied")
	ErrIncompleteMigration  = errors.New("incomplete non-transactional migration; inspect database state before recovery")
	ErrUnknownApplied       = errors.New("database contains a migration not registered in code")
	ErrOutOfOrderMigration  = errors.New("pending migration precedes an applied migration")
)

Functions

func IsValidMigrationName 

func IsValidMigrationName(name string) bool

IsValidMigrationName reports whether name is a valid migration name. Valid names contain only lowercase letters, digits, and underscores.

func IsValidMigrationVersion 

func IsValidMigrationVersion(version string) bool

IsValidMigrationVersion reports whether version is a valid migration version. Valid versions contain only letters, digits, dots, dashes, and underscores.

Types

type Applied 

type Applied struct {
	Version      string
	Name         string
	AppliedAt    time.Time
	Checksum     string
	AppliedBy    string
	DurationMS   int64
	Hostname     string
	Environment  string
	Action       string
	Status       string
	ErrorMessage string
}

Applied represents a migration that has been applied.

type Config 

type Config struct {
	TableName      string
	LockTimeout    time.Duration
	SkipLock       bool
	Naming         *NamingConfig
	IsolationLevel sql.IsolationLevel
	// AllowUnknownApplied permits database versions absent from this process's registry.
	// Useful during rolling deploys with mixed application versions.
	AllowUnknownApplied bool
	// AllowOutOfOrder permits applying a newly registered older version.
	AllowOutOfOrder bool
}

Config configures Queen behavior.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns default configuration.

type Driver 

type Driver interface {
	Init(ctx context.Context) error
	GetApplied(ctx context.Context) ([]Applied, error)
	Record(ctx context.Context, m *Migration, meta *MigrationMetadata) error
	Remove(ctx context.Context, version string) error
	Lock(ctx context.Context, timeout time.Duration) error
	Unlock(ctx context.Context) error
	Exec(ctx context.Context, isolationLevel sql.IsolationLevel, fn func(*sql.Tx) error) error
	Close() error
}

Driver is the interface that database-specific migration drivers must implement.

type Gap 

type Gap struct {
	Type        GapType  `json:"type"`
	Version     string   `json:"version"`
	Name        string   `json:"name,omitempty"`
	Description string   `json:"description"`
	Severity    string   `json:"severity"`
	AppliedAt   *string  `json:"applied_at,omitempty"`
	BlockedBy   []string `json:"blocked_by,omitempty"`
}

type GapType 

type GapType string
const (
	GapTypeNumbering    GapType = "numbering"
	GapTypeApplication  GapType = "application"
	GapTypeUnregistered GapType = "unregistered"
)

type IgnoredGap 

type IgnoredGap struct {
	Version   string
	Reason    string
	IgnoredAt time.Time
	IgnoredBy string
}

type Logger 

type Logger interface {
	InfoContext(ctx context.Context, msg string, args ...any)
	WarnContext(ctx context.Context, msg string, args ...any)
	ErrorContext(ctx context.Context, msg string, args ...any)
}

Logger is a structured logging interface compatible with slog.Logger.

type M 

type M = Migration

type Migration 

type Migration struct {
	Version        string
	Name           string
	UpSQL          string
	DownSQL        string
	UpFunc         MigrationFunc
	DownFunc       MigrationFunc
	ManualChecksum string
	IsolationLevel sql.IsolationLevel
	// SQLLockTimeout limits time spent waiting for a PostgreSQL table/row lock.
	SQLLockTimeout time.Duration
	// StatementTimeout limits execution time for this migration's SQL.
	StatementTimeout time.Duration
	// NonTransactional permits one PostgreSQL SQL command outside a transaction.
	NonTransactional bool
}

Migration represents a database migration.

func (*Migration) Checksum 

func (m *Migration) Checksum() string

func (*Migration) HasRollback 

func (m *Migration) HasRollback() bool

func (*Migration) IsDestructive 

func (m *Migration) IsDestructive() bool

func (*Migration) Validate 

func (m *Migration) Validate() error

type MigrationError 

type MigrationError struct {
	Version   string
	Name      string
	Operation string
	Driver    string
	Cause     error
}

MigrationError wraps an error with migration context.

func (*MigrationError) Error 

func (e *MigrationError) Error() string

func (*MigrationError) Unwrap 

func (e *MigrationError) Unwrap() error

type MigrationExecutor 

type MigrationExecutor interface {
	ExecMigration(ctx context.Context, m *Migration, isolationLevel sql.IsolationLevel, fn func(*sql.Tx) error) error
}

MigrationExecutor applies per-migration SQL timeouts within a transaction.

type MigrationFunc 

type MigrationFunc func(ctx context.Context, tx *sql.Tx) error

type MigrationMetadata 

type MigrationMetadata struct {
	AppliedBy    string
	DurationMS   int64
	Hostname     string
	Environment  string
	Action       string
	Status       string
	ErrorMessage string
}

MigrationMetadata contains metadata collected during migration execution.

type MigrationPlan 

type MigrationPlan struct {
	Version       string        `json:"version"`
	Name          string        `json:"name"`
	Direction     string        `json:"direction"`
	Status        string        `json:"status"`
	Type          MigrationType `json:"type"`
	SQL           string        `json:"sql,omitempty"`
	HasRollback   bool          `json:"has_rollback"`
	IsDestructive bool          `json:"is_destructive"`
	Checksum      string        `json:"checksum"`
	Warnings      []string      `json:"warnings,omitempty"`
}

MigrationPlan represents a migration execution plan.

type MigrationStatus 

type MigrationStatus struct {
	Version     string
	Name        string
	Status      Status
	AppliedAt   *time.Time
	Checksum    string
	HasRollback bool
	Destructive bool
}

MigrationStatus represents the current state of a migration.

type MigrationType 

type MigrationType string
const (
	MigrationTypeSQL    MigrationType = "sql"
	MigrationTypeGoFunc MigrationType = "go-func"
	MigrationTypeMixed  MigrationType = "mixed"
)

type NamingConfig 

type NamingConfig struct {
	Pattern NamingPattern
	Padding int
	Enforce bool
}

func DefaultNamingConfig 

func DefaultNamingConfig() *NamingConfig

func (*NamingConfig) FindNextVersion 

func (nc *NamingConfig) FindNextVersion(existingVersions []string) (string, error)

func (*NamingConfig) Validate 

func (nc *NamingConfig) Validate(version string) error

type NamingPattern 

type NamingPattern string
const (
	NamingPatternNone             NamingPattern = ""
	NamingPatternSequential       NamingPattern = "sequential"
	NamingPatternSequentialPadded NamingPattern = "sequential-padded"
	NamingPatternSemver           NamingPattern = "semver"
)

type NonTransactionalExecutor 

type NonTransactionalExecutor interface {
	ExecNonTransactional(ctx context.Context, m *Migration, direction string) error
	SetMigrationStatus(ctx context.Context, version, status string, durationMS int64) error
}

NonTransactionalExecutor supports SQL commands that cannot run in a transaction. SetMigrationStatus persists the recovery state before and after the command.

type Option 

type Option func(*Queen)

Option configures a Queen instance.

func WithLogger 

func WithLogger(logger Logger) Option

WithLogger sets a custom logger. Compatible with *slog.Logger.

func WithTap 

func WithTap(sink tap.Sink) Option

WithTap installs a tap.Sink that receives a start/exec/end event for every migration. SQL migrations emit a single exec event with the full SQL text; Go-function migrations can opt into per-statement tapping by calling tap.ObserveTx(ctx, tx) and using the wrapper's ExecContext/QueryContext methods.

type Queen 

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

Queen manages database migrations.

func New 

func New(driver Driver, opts ...Option) *Queen

New creates a Queen instance with default configuration.

func NewWithConfig 

func NewWithConfig(driver Driver, config *Config, opts ...Option) *Queen

NewWithConfig creates a Queen instance with custom configuration.

func (*Queen) Add 

func (q *Queen) Add(m M) error

Add registers a migration. Returns ErrVersionConflict if version already exists.

func (*Queen) Close 

func (q *Queen) Close() error

Close releases database resources.

func (*Queen) DetectGaps 

func (q *Queen) DetectGaps(ctx context.Context) ([]Gap, error)

DetectGaps analyzes migrations and returns any detected gaps.

func (*Queen) Down 

func (q *Queen) Down(ctx context.Context, n int) (retErr error)

Down rolls back the last n migrations. If n <= 0, rolls back only the last migration.

Example

ExampleQueen_Down demonstrates rolling back migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	ctx := context.Background()

	// Rollback last migration
	if err := q.Down(ctx, 1); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Rolled back 1 migration")
}

func (*Queen) Driver 

func (q *Queen) Driver() Driver

Driver returns the underlying database driver.

func (*Queen) DriverName 

func (q *Queen) DriverName() string

DriverName returns the normalized database driver name used in diagnostics.

func (*Queen) DryRun 

func (q *Queen) DryRun(ctx context.Context, direction string, limit int) ([]MigrationPlan, error)

DryRun returns a migration execution plan without applying migrations. Direction can be DirectionUp (pending) or DirectionDown (applied).

func (*Queen) Explain 

func (q *Queen) Explain(ctx context.Context, version string) (*MigrationPlan, error)

Explain returns a detailed migration plan for a specific version.

func (*Queen) FindMigration 

func (q *Queen) FindMigration(version string) *Migration

FindMigration returns a registered migration by version, or nil if not found.

func (*Queen) MustAdd 

func (q *Queen) MustAdd(m M)

MustAdd is like Add but panics on error.

func (*Queen) RegisteredMigrations 

func (q *Queen) RegisteredMigrations() []Migration

RegisteredMigrations returns copies of registered migrations in version order. It does not initialize or query the database.

func (*Queen) Reset 

func (q *Queen) Reset(ctx context.Context) (retErr error)

Reset rolls back all applied migrations.

Example

ExampleQueen_Reset demonstrates rolling back all migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	ctx := context.Background()
	if err := q.Reset(ctx); err != nil {
		log.Fatal(err)
	}

	fmt.Println("All migrations rolled back")
}

func (*Queen) ResolveIncomplete 

func (q *Queen) ResolveIncomplete(ctx context.Context, version, resolution string) (retErr error)

ResolveIncomplete updates the migration record after an operator has checked the database schema. It never runs migration SQL. The version must still be registered with the same checksum as the interrupted migration.

func (*Queen) SQLDB 

func (q *Queen) SQLDB() *sql.DB

SQLDB returns the underlying database handle when the driver exposes one. It is primarily used by interactive diagnostics such as EXPLAIN.

func (*Queen) SetTap 

func (q *Queen) SetTap(sink tap.Sink)

SetTap replaces the active tap sink. It is intended for interactive tools that need to enable tap only around a specific operation.

func (*Queen) Status 

func (q *Queen) Status(ctx context.Context) ([]MigrationStatus, error)

Status returns the status of all registered migrations.

func (*Queen) Up 

func (q *Queen) Up(ctx context.Context) error

Up applies all pending migrations. Equivalent to UpSteps(ctx, 0).

Example

ExampleQueen_Up demonstrates applying all pending migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	q.MustAdd(queen.M{
		Version: "001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id INT)`,
		DownSQL: `DROP TABLE users`,
	})

	ctx := context.Background()
	if err := q.Up(ctx); err != nil {
		log.Fatal(err)
	}

	fmt.Println("All migrations applied")
}

func (*Queen) UpSteps 

func (q *Queen) UpSteps(ctx context.Context, n int) (retErr error)

UpSteps applies up to n pending migrations. If n <= 0, applies all.

Example

ExampleQueen_UpSteps demonstrates applying a specific number of migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	q.MustAdd(queen.M{Version: "001", Name: "migration_1", UpSQL: "..."})
	q.MustAdd(queen.M{Version: "002", Name: "migration_2", UpSQL: "..."})
	q.MustAdd(queen.M{Version: "003", Name: "migration_3", UpSQL: "..."})

	ctx := context.Background()

	// Apply only the next 2 migrations
	if err := q.UpSteps(ctx, 2); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Applied 2 migrations")
}

func (*Queen) Validate 

func (q *Queen) Validate(ctx context.Context) error

Validate checks for duplicate versions, invalid migrations, and checksum mismatches.

Example

ExampleQueen_Validate demonstrates validating migrations. 

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	driver := mock.New()
	q := queen.New(driver)
	defer func() { _ = q.Close() }()

	q.MustAdd(queen.M{
		Version: "001",
		Name:    "create_users",
		UpSQL:   `CREATE TABLE users (id INT)`,
	})

	ctx := context.Background()
	if err := q.Validate(ctx); err != nil {
		log.Fatalf("Validation failed: %v", err)
	}

	fmt.Println("All migrations valid")
}

type QueenIgnore 

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

func LoadQueenIgnore 

func LoadQueenIgnore() (*QueenIgnore, error)

func LoadQueenIgnoreFrom 

func LoadQueenIgnoreFrom(path string) (*QueenIgnore, error)

func (*QueenIgnore) AddIgnore 

func (qi *QueenIgnore) AddIgnore(version, reason, ignoredBy string) error

func (*QueenIgnore) GetReason 

func (qi *QueenIgnore) GetReason(version string) string

func (*QueenIgnore) IsIgnored 

func (qi *QueenIgnore) IsIgnored(version string) bool

func (*QueenIgnore) ListIgnored 

func (qi *QueenIgnore) ListIgnored() []*IgnoredGap

func (*QueenIgnore) RemoveIgnore 

func (qi *QueenIgnore) RemoveIgnore(version string) error

func (*QueenIgnore) Save 

func (qi *QueenIgnore) Save() error

type SQLDBProvider 

type SQLDBProvider interface {
	SQLDB() *sql.DB
}

SQLDBProvider is implemented by drivers that can expose their underlying database handle for optional diagnostics such as EXPLAIN.

type Status 

type Status int
const (
	StatusPending Status = iota
	StatusApplied
	StatusModified
	StatusIncomplete
)

func (Status) String 

func (s Status) String() string

type TestHelper 

type TestHelper struct {
	*Queen
	// contains filtered or unexported fields
}

TestHelper provides testing utilities for migrations.

func NewTest 

func NewTest(t *testing.T, driver Driver) *TestHelper
Example

ExampleNewTest demonstrates using the testing helper. 

package main

import (
	"fmt"
	"testing"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	testFunc := func(t *testing.T) {
		driver := setupTestDB(t)

		// NewTest automatically cleans up when test ends
		q := queen.NewTest(t, driver)

		q.MustAdd(queen.M{
			Version: "001",
			Name:    "create_users",
			UpSQL:   `CREATE TABLE users (id INT)`,
			DownSQL: `DROP TABLE users`,
		})

		// Test migrations
		q.MustUp()
		q.MustValidate()

		fmt.Println("Test passed")
	}

	t := &testing.T{}
	testFunc(t)
}

func setupTestDB(_ *testing.T) queen.Driver {

	return mock.New()
}

func (*TestHelper) MustDown 

func (th *TestHelper) MustDown(n int)

func (*TestHelper) MustReset 

func (th *TestHelper) MustReset()

func (*TestHelper) MustUp 

func (th *TestHelper) MustUp()

func (*TestHelper) MustValidate 

func (th *TestHelper) MustValidate()

func (*TestHelper) TestRollback 

func (th *TestHelper) TestRollback()
Example

ExampleTestHelper_TestRollback demonstrates thorough testing of down migrations. 

package main

import (
	"fmt"
	"testing"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	testFunc := func(t *testing.T) {
		driver := setupTestDB(t)
		q := queen.NewTest(t, driver)

		q.MustAdd(queen.M{
			Version: "001",
			Name:    "create_users",
			UpSQL:   `CREATE TABLE users (id INT)`,
			DownSQL: `DROP TABLE users`,
		})

		q.MustAdd(queen.M{
			Version: "002",
			Name:    "add_email",
			UpSQL:   `ALTER TABLE users ADD COLUMN email VARCHAR(255)`,
			DownSQL: `ALTER TABLE users DROP COLUMN email`,
		})

		// TestRollback performs a full cycle: Up -> Down (one by one) -> Up
		// This catches broken Down migrations that don't properly undo their Up
		q.TestRollback()

		fmt.Println("All down migrations work correctly")
	}

	t := &testing.T{}
	testFunc(t)
}

func setupTestDB(_ *testing.T) queen.Driver {

	return mock.New()
}

func (*TestHelper) TestUpDown 

func (th *TestHelper) TestUpDown()
Example

ExampleTestHelper_TestUpDown demonstrates testing up and down migrations. 

package main

import (
	"fmt"
	"testing"

	"github.com/dmedovich/queen"
	"github.com/dmedovich/queen/drivers/mock"
)

func main() {
	testFunc := func(t *testing.T) {
		driver := setupTestDB(t)
		q := queen.NewTest(t, driver)

		q.MustAdd(queen.M{
			Version: "001",
			Name:    "create_users",
			UpSQL:   `CREATE TABLE users (id INT)`,
			DownSQL: `DROP TABLE users`,
		})

		// TestUpDown applies all migrations, then rolls them back
		q.TestUpDown()

		fmt.Println("Up and down migrations work correctly")
	}

	t := &testing.T{}
	testFunc(t)
}

func setupTestDB(_ *testing.T) queen.Driver {

	return mock.New()
}

type TransactionalRecorder 

type TransactionalRecorder interface {
	RecordTx(ctx context.Context, tx *sql.Tx, m *Migration, meta *MigrationMetadata) error
	RemoveTx(ctx context.Context, tx *sql.Tx, version string) error
}

TransactionalRecorder is an optional Driver capability. When implemented, Queen records or removes the migration row inside the same transaction as the migration body, so schema/data changes and migration metadata commit together.

Source Files

View all Source files

Directories

Path Synopsis
cli
Package cli provides a command-line interface for Queen migrations.
 Package cli provides a command-line interface for Queen migrations.
commands/importcmd
tui
Package tui provides a terminal UI for Queen migrations.
 Package tui provides a terminal UI for Queen migrations.
tui/live
Package live renders a Bubble Tea live-view of queen migration tap events.
 Package live renders a Bubble Tea live-view of queen migration tap events.
drivers
base
Package base provides common functionality for Queen database drivers.
 Package base provides common functionality for Queen database drivers.
clickhouse
Package clickhouse provides a ClickHouse driver for Queen migrations.
 Package clickhouse provides a ClickHouse driver for Queen migrations.
cockroachdb
Package cockroachdb provides a CockroachDB driver for Queen migrations.
 Package cockroachdb provides a CockroachDB driver for Queen migrations.
mock
Package mock provides an in-memory mock driver for testing Queen without a real database.
 Package mock provides an in-memory mock driver for testing Queen without a real database.
mssql
Package mssql provides a MS SQL Server driver for Queen migrations.
 Package mssql provides a MS SQL Server driver for Queen migrations.
mysql
Package mysql provides a MySQL driver for Queen migrations.
 Package mysql provides a MySQL driver for Queen migrations.
postgres
Package postgres provides a PostgreSQL driver for Queen migrations.
 Package postgres provides a PostgreSQL driver for Queen migrations.
sqlite
Package sqlite provides a SQLite driver for Queen migrations.
 Package sqlite provides a SQLite driver for Queen migrations.
internal
checksum
Package checksum provides checksum calculation for migrations.
 Package checksum provides checksum calculation for migrations.
sort
Package sort compares migration versions in natural order.
 Package sort compares migration versions in natural order.
Package tap provides real-time observability of SQL executed during queen migrations.
 Package tap provides real-time observability of SQL executed during queen migrations.
tests
demodata
Package demodata registers one shared migration story for Queen demos.
 Package demodata registers one shared migration story for Queen demos.
tapdemo command
tapdemo is a focused development preview for the low-level tap live renderer.
 tapdemo is a focused development preview for the low-level tap live renderer.
tuidemo command
tuidemo launches the main Queen TUI against an in-memory SQLite database.
 tuidemo launches the main Queen TUI against an in-memory SQLite database.
website
examples/basic-migrator/cmd/migrate command
examples/basic-migrator/migrations

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.