Documentation
¶
Overview ¶
Package migrations provides utilities for managing database migrations in test environments. It offers a flexible and composable system for applying database migrations as part of integration testing setups.
The package provides:
- Migrations interface for defining migration operations
- Up function for converting Migrations to dbenv.Option
- Multi function for composing multiple migrations
- Goose migration adapter for goose-based migrations
For SQL-based migrations, use dbenv.Queries from the dbenv package.
Example Usage:
// Create a simple SQL migration option using dbenv.Queries
opt := dbenv.Queries(
"CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)",
"CREATE INDEX idx_users_name ON users(name)",
)
// Use with dbenv.Use or dbenv.UseForTesting
db, err := dbenv.Use(ctx, env, opt)
if err != nil {
return err
}
defer db.Close()
// Database is now migrated and ready to use
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Nil nilMigrations
Nil is a no-op migration that does nothing when applied. It can be used as a placeholder or when no migrations are needed.
Functions ¶
func Up ¶
Up converts a Migrations implementation to an option function that can be passed to dbenv.Use or dbenv.UseForTesting. This allows any Migrations implementation to be used as a connection option.
Parameters:
- m: Migrations to convert to an option
Returns:
- func(ctx context.Context, db *sql.DB) error: An option function
Example:
// Using with goose migrations
gooseMigrations := goosemigrations.New(migrationFS)
db, err := dbenv.Use(ctx, env, migrations.Up(gooseMigrations))
// Using with custom migrations
type MyMigrations struct{}
func (m *MyMigrations) Up(ctx context.Context, db *sql.DB) error {
// Apply migrations
return nil
}
db := dbenv.UseForTesting(t, env, migrations.Up(&MyMigrations{}))
Types ¶
type Migrations ¶
type Migrations interface {
// Up applies the migration to the database.
// This method is called when the option is applied during connection.
//
// Parameters:
// - ctx: Context for cancellation and timeout
// - db: Database connection to apply migrations to
//
// Returns:
// - error: Non-nil if the migration fails
Up(ctx context.Context, db *sql.DB) error
}
Migrations defines the interface for database migration operations. Implementations of this interface can define how to apply migrations to a database connection.
The most common implementations are:
- Goose: For goose-based migrations (see goosemigrations package)
- Multi: For composing multiple migrations
- Nil: For no-op migrations
For simple SQL queries, use dbenv.Queries from the dbenv package instead of implementing this interface.
To use a Migrations with dbenv.Use or dbenv.UseForTesting, convert it to an option using the Up function:
db, err := dbenv.Use(ctx, env, migrations.Up(myMigrations))
func Multi ¶
func Multi(migrations ...Migrations) Migrations
Multi creates a Migrations implementation that applies multiple migrations in sequence. If any migration fails, the sequence stops and the error is returned.
Parameters:
- migrations: Migrations to compose (applied in order)
Returns:
- Migrations: A composed migration that runs all migrations in sequence
Example:
// Compose multiple migrations
multi := Multi(
Queries("CREATE TABLE users (id SERIAL PRIMARY KEY)"),
Queries("CREATE TABLE posts (id SERIAL PRIMARY KEY, user_id INT)"),
gooseMigrations,
)
// Use with dbenv
db, err := dbenv.Use(ctx, env, Up(multi))
Source Files
Directories