migrate

README

migrate

Dead simple in-app migration system.

Install

go get github.com/struct0x/migrate

Usage

In your module, declare migrations

package users

import "github.com/struct0x/migrate"

var StoreMigrations = migrate.Migrations{
	ModuleName: "users",
	Migrations: []migrate.Migration{
		{
			Name: "001_create_users",
			SQL: `CREATE TABLE users (
              id   TEXT PRIMARY KEY,
              name TEXT NOT NULL
			)`,
		},
		{
			Name: "002_add_email",
			SQL:  `ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ''`,
		},
	},
}

At startup, pass all module groups together:

package main

func main() {
	// ...
	if err := migrate.Migrate(ctx, db, migrate.Postgres,
		users.StoreMigrations,
		payments.StoreMigrations,
		licensing.StoreMigrations,
	); err != nil {
		return fmt.Errorf("migrate: %w", err)
	}
}

Dialects

Dialect	Var
SQLite	migrate.SQLite
PostgreSQL	migrate.Postgres
MySQL	migrate.MySQL

Options

Option	Description
WithLogger(*slog.Logger)	Sets the logger used to print what migrations were run.

Behavior

• Idempotent — safe to call on every startup
• Concurrent-safe — multiple processes can call Migrate simultaneously
• Each migration runs exactly once
• A failed migration is rolled back and returns an error; subsequent migrations in the group are not applied

License

MIT License

Documentation

Index

• Variables
• func Migrate(ctx context.Context, db *sql.DB, dialect Dialect, opts ...Option) error
• type Dialect
• type Migration
• type Migrations
• type Option
  • func WithLogger(logger *slog.Logger) Option

Variables

var (
	SQLite = Dialect{
			// contains filtered or unexported fields
	}
	Postgres = Dialect{
				// contains filtered or unexported fields
	}
	MySQL = Dialect{
			// contains filtered or unexported fields
	}
)

Functions

func Migrate

func Migrate(
	ctx context.Context,
	db *sql.DB,
	dialect Dialect,
	opts ...Option,
) error

Migrate runs database migrations in a safe and idempotent way.

It creates a schema_migrations table if it doesn't exist, then applies each migration exactly once by claiming it first. Migrations are grouped by module name and executed in order. Each migration runs in its own transaction - if it fails, the transaction is rolled back and an error is returned.

The function is safe for concurrent execution: only one instance will successfully claim and apply each migration. Already applied migrations are skipped automatically.

Parameters:

• ctx: context for cancellation and timeout control
• db: database connection to run migrations on
• dialect: database-specific SQL syntax (SQLite, Postgres, or MySQL)
• opts: optional configuration (migrations to run, logger for output)

Returns an error if table creation fails, transaction handling fails, or any migration SQL fails to execute.

Types

type Dialect

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

type Migration

type Migration struct {
	Name string
	SQL  string
}

type Migrations

type Migrations struct {
	ModuleName string
	Migrations []Migration
}

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithLogger

func WithLogger(logger *slog.Logger) Option