migrate

README

database/migrate

The migrate package provides schema migration and seed data execution. It is built on top of golang-migrate and is intended for services that need to apply versioned SQL migrations and optional seed files at startup.

Import

import "github.com/raykavin/gobox/database/migrate"

What it provides

• Migrator for applying pending schema migrations from a local directory
• Populate for executing seed .sql files in directory order
• support for postgres, mysql, and sqlite3
• dirty-state detection before applying migrations
• context-aware execution with cancellation checks

Main types

• MigrateConfig: connection and path settings
• Migrator: runs migrations and population against the configured database

Example

package main

import (
    "context"
    "log"

    "github.com/raykavin/gobox/database/migrate"
)

func main() {
    ctx := context.Background()

    m, err := migrate.New(migrate.MigrateConfig{
        DSN:            "postgres://user:pass@localhost/mydb?sslmode=disable",
        Dialector:      "postgres",
        MigrationsPath: "./migrations",
        PopulationPath: "./seeds",
    })
    if err != nil {
        log.Fatal(err)
    }

    if err := m.Migrate(ctx); err != nil {
        log.Fatal(err)
    }

    if err := m.Populate(ctx); err != nil {
        log.Fatal(err)
    }
}

Migration file naming

Files follow the golang-migrate convention:

migrations/
  000001_create_users.up.sql
  000001_create_users.down.sql
  000002_add_email_index.up.sql
  000002_add_email_index.down.sql

Errors

Sentinel	Cause
ErrInvalidConfig	required field missing or dialector not supported
ErrDatabaseConnectionFailed	sql.Open failed
ErrDatabasePingFailed	database unreachable after open
ErrDatabaseDirtyState	previous migration left the database in a dirty state
ErrMigrationFailed	migrate.Up() returned an unexpected error
ErrReadPopulationDirectory	PopulationPath could not be read
ErrPopulateExecutionFailed	a seed file failed to execute

Notes

• Migrate is a no-op when there are no pending migrations
• Populate is a no-op when PopulationPath is empty
• seed files are executed in the order returned by os.ReadDir, which is alphabetical
• if the database is in a dirty state, manual intervention is required before migrations can proceed

Documentation

Overview

Package migrate provides schema migration and seed data execution using golang-migrate.

It supports PostgreSQL, MySQL, and SQLite. Migration files are read from the local filesystem; seed files are plain .sql files executed in directory order.

Basic usage

m, err := migrate.New(migrate.MigrateConfig{
    DSN:            "postgres://user:pass@localhost/mydb?sslmode=disable",
    Dialector:      "postgres",
    MigrationsPath: "./migrations",
})
if err != nil {
    log.Fatal(err)
}
defer m.Close()

if err := m.Migrate(ctx); err != nil {
    log.Fatal(err)
}

Seeding

Populate executes all .sql files found in PopulationPath in alphabetical order. It is a no-op when PopulationPath is empty.

m, _ := migrate.New(migrate.MigrateConfig{
    DSN:            dsn,
    Dialector:      "postgres",
    MigrationsPath: "./migrations",
    PopulationPath: "./seeds",
})

_ = m.Migrate(ctx)
_ = m.Populate(ctx)

Index

• Variables
• type MigrateConfig
• type Migrator
  • func New(config MigrateConfig) (*Migrator, error)
  • func (m *Migrator) Migrate(ctx context.Context) error
  • func (m *Migrator) Populate(ctx context.Context) error

Variables

var (
	ErrInvalidConfig            = errors.New("invalid configuration")
	ErrDatabaseConnectionFailed = errors.New("failed to open database connection")
	ErrDatabasePingFailed       = errors.New("failed to ping database")
	ErrAbsolutePathFailed       = errors.New("failed to resolve absolute path")
	ErrMigrateInstanceFailed    = errors.New("failed to create migrate instance")
	ErrGetVersionFailed         = errors.New("failed to get current migration version")
	ErrDatabaseDirtyState       = errors.New("database is in a dirty state, manual intervention required")
	ErrMigrationFailed          = errors.New("failed to apply migrations")
	ErrGetNewVersionFailed      = errors.New("failed to get new migration version after applying")
	ErrReadPopulationDirectory  = errors.New("failed to read population directory")
	ErrReadPopulateFile         = errors.New("failed to read seed file")
	ErrPopulateExecutionFailed  = errors.New("failed to execute seed file")
	ErrDSNRequired              = errors.New("dsn is required")
	ErrDialectorRequired        = errors.New("dialector is required")
	ErrMigrationsPathRequired   = errors.New("migrations path is required")
	ErrInvalidMigrationsPath    = errors.New("migrations path does not exist")
	ErrUnsupportedDialect       = errors.New("unsupported database dialect")
)

Types

type MigrateConfig

type MigrateConfig struct {
	DSN            string
	Dialector      string
	MigrationsPath string
	PopulationPath string
}

MigrateConfig holds the database and migration settings.

type Migrator

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

Migrator applies schema migrations and seed data using golang-migrate.

func New

func New(config MigrateConfig) (*Migrator, error)

New creates a new Migrator, opening and validating the database connection.

func (*Migrator) Migrate

func (m *Migrator) Migrate(ctx context.Context) error

Migrate applies all pending migrations.

func (*Migrator) Populate

func (m *Migrator) Populate(ctx context.Context) error

Populate executes all .sql files in the configured PopulationPath.