Database migrations
without the pain.

00 Installation

GoMigrate has three audiences, each with a different installation path. Most developers fall into one of the first two — you only need to clone the repo if you want to contribute code.

Path A — Install the CLI

With Go 1.22+ installed, a single command:

$ go install github.com/taqnihub/gomigrate@latest

Verify the installation:

$ gomigrate --version
gomigrate version 0.1.0

$ export PATH="$PATH:$(go env GOPATH)/bin"

Path B — Use as a Go library

Inside your Go project, add it as a dependency:

$ go get github.com/taqnihub/gomigrate@latest

Then import the packages you need:

import (
    "github.com/taqnihub/gomigrate/config"
    "github.com/taqnihub/gomigrate/migrate"
)

See Part Two below for usage examples.

Path C — Clone the repo (contributors only)

This path is only for developers who want to contribute code, fix bugs, or modify the library itself. You don't need this to use gomigrate.

$ git clone https://github.com/taqnihub/gomigrate.git
$ cd gomigrate
$ go build -o gomigrate .
$ ./gomigrate --help

01 Quick Start

Copy-paste this into your terminal and you'll be running migrations in under a minute. Every step is intentional — skip none.

# 1. Install the CLI
$ go install github.com/taqnihub/gomigrate@latest

# 2. Verify it's installed
$ gomigrate --version

# 3. Initialize gomigrate in your project (interactive wizard)
$ gomigrate init

# 4. Create your first migration (generates .up.sql and .down.sql)
$ gomigrate create add_users_table

# 5. Edit the generated SQL files in ./db/migrations/
#    (add your CREATE TABLE, ALTER TABLE, etc.)

# 6. Check what's pending
$ gomigrate status

# 7. Apply all pending migrations
$ gomigrate up

# 8. Verify everything was applied
$ gomigrate status

# 9. If you need to undo the last migration
$ gomigrate down

# 10. Or launch the interactive TUI menu
$ gomigrate

Complete command reference

Every command gomigrate understands, grouped by purpose. Each row shows the command syntax, a description, and a concrete example you can run.

Global flags (work with any command)

Initialize a project

Inside the root of your project, run gomigrate init. You'll be walked through an interactive wizard that asks for your driver, connection details, and migrations directory.

$ gomigrate init

🚀 Welcome to GoMigrate

? Database driver:
  > MySQL
    PostgreSQL

? Host: localhost
? Port: 3306
? Database name: myapp
? Username: root
? Password: ********
? Migrations directory: ./db/migrations

✓ GoMigrate initialized!
  Config:      /path/to/project/.gomigrate.yml
  Migrations:  /path/to/project/db/migrations

This creates two things:

• .gomigrate.yml — a config file with your connection details
• ./db/migrations/ — an empty directory where your SQL files will live

Creating a migration

Run gomigrate create with a descriptive name. Two timestamped SQL files will be generated — one for applying the change, one for reverting it.

$ gomigrate create add_users_table

✨ Creating Migration

  ✓ Created migration files

  UP:    db/migrations/20260417103045_add_users_table.up.sql
  DOWN:  db/migrations/20260417103045_add_users_table.down.sql

  Next: edit the files with your SQL, then run  gomigrate up

Naming conventions

Now open the generated files and write your SQL. Example for users:

-- up.sql
CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  email VARCHAR(255) NOT NULL UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- down.sql
DROP TABLE IF EXISTS users;

Applying & reverting

To apply every pending migration in order, just run:

$ gomigrate up

⚡ Applying Migrations

  Database:  mysql on localhost:3306/myapp

  Will apply 3 migration(s):
    →  20260417103045  add_users_table
    →  20260417103112  add_products_table
    →  20260417103158  add_orders_table

    ✓  20260417103045  add_users_table
    ✓  20260417103112  add_products_table
    ✓  20260417103158  add_orders_table

  ✓ Applied 3 migration(s) in 12ms
  Version:   0 → 20260417103158

Apply only the next N migrations by passing a number:

$ gomigrate up 1    # apply just the next one
$ gomigrate up 3    # apply the next three

Reverting

To undo the most recent migration:

$ gomigrate down

⬇  Reverting Migrations

  Database:  mysql on localhost:3306/myapp

  Will revert 1 migration(s):
    ←  20260417103158  add_orders_table

    ✓  20260417103158  add_orders_table

  ✓ Reverted 1 migration(s) in 6ms
  Version:   20260417103158 → 20260417103112

Revert N migrations, or use --all to revert everything:

$ gomigrate down 3          # revert the last three
$ gomigrate down --all      # revert ALL (destructive)

Checking status

See which migrations are applied and which are pending:

$ gomigrate status

📋 Migration Status

  Database:   mysql on localhost:3306/myapp
  Directory:  ./db/migrations

   VERSION           NAME                      STATUS
   ──────────────────────────────────────────────────────
   20260417103045    add_users_table           ✓ applied
   20260417103112    add_products_table        ✓ applied
   20260417103158    add_orders_table          ○ pending

  3 total · 2 applied · 1 pending

Fixing a dirty state

If a migration fails halfway through, GoMigrate marks the database as dirty and refuses to run further migrations until you resolve it. First, manually fix the schema in your database. Then tell GoMigrate what version the schema actually matches:

$ gomigrate force 20260417103112

🔧 Forcing Migration Version

  ✓ Version forced to 20260417103112

  ⚠ No SQL was executed.
     Make sure your database schema matches this version!

Interactive mode

Run gomigrate with no arguments to get a keyboard-navigable menu:

$ gomigrate

⚡ GoMigrate
mysql · localhost:3306 · myapp

What would you like to do?

  > ▶  Apply migrations
    ◀  Revert last migration
    ✚  Create new migration
    📋 View status
    🔧 Force version
    q  Quit

↑/↓ navigate · enter select · q quit

Use arrow keys (or j/k for vim users) to move, Enter to select, and q or Esc to quit.

Configuration

GoMigrate reads settings from multiple sources, applied in this order (highest priority first):

1. CLI flags — e.g. --driver postgres
2. Environment variables with the GOMIGRATE_ prefix
3. .gomigrate.yml in the current directory
4. .gomigrate.yml in your home directory
5. Sensible defaults

Config file reference

# .gomigrate.yml
driver: mysql              # mysql or postgres
host: localhost
port: 3306
database: myapp
user: root
password: secret
migrations_dir: ./db/migrations

# Optional
ssl_mode: disable            # disable | require | verify-full
timezone: UTC
lock_timeout: 15s

Using environment variables

Any config value can be overridden with a GOMIGRATE_-prefixed variable. This is how you should handle secrets in CI/CD:

$ export GOMIGRATE_DRIVER=postgres
$ export GOMIGRATE_HOST=prod-db.example.com
$ export GOMIGRATE_PASSWORD="$DB_PASSWORD"
$ gomigrate up

Basic usage

The canonical five-line example:

package main

import (
    "log"

    "github.com/taqnihub/gomigrate/config"
    "github.com/taqnihub/gomigrate/migrate"
)

func main() {
    cfg, _ := config.Load("")            // reads .gomigrate.yml + env vars
    engine, _ := migrate.New(cfg)
    defer engine.Close()

    if err := engine.Up(); err != nil {
        log.Fatal(err)
    }
}

This does exactly what gomigrate up does on the command line — but from inside your own Go program.

Auto-migrate on app startup

A common pattern: have your web server apply any pending migrations before it starts serving traffic. This guarantees your schema is always in sync with your deployed code.

package main

import (
    "errors"
    "log"
    "net/http"

    "github.com/taqnihub/gomigrate/config"
    "github.com/taqnihub/gomigrate/migrate"
)

func main() {
    // 1. Load config
    cfg, err := config.Load("")
    if err != nil {
        log.Fatalf("config: %v", err)
    }

    // 2. Create engine and apply pending migrations
    engine, err := migrate.New(cfg)
    if err != nil {
        log.Fatalf("migrate init: %v", err)
    }
    defer engine.Close()

    if err := engine.Up(); err != nil {
        // ErrNoChange means we're already up-to-date — that's fine
        if !errors.Is(err, migrate.ErrNoChange) {
            log.Fatalf("migration failed: %v", err)
        }
    }

    // 3. Log current state
    version, dirty, _ := engine.Version()
    log.Printf("DB at version %d (dirty=%v)", version, dirty)

    // 4. Start your server
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Programmatic configuration

You don't need a YAML file. Build a config.Config struct directly — useful when your app composes config from multiple sources (secret managers, Consul, AWS Parameter Store, etc.):

package main

import (
    "log"
    "os"

    "github.com/taqnihub/gomigrate/config"
    "github.com/taqnihub/gomigrate/migrate"
)

func main() {
    cfg := &config.Config{
        Driver:        "postgres",
        Host:          os.Getenv("DB_HOST"),
        Port:          5432,
        Database:      os.Getenv("DB_NAME"),
        User:          os.Getenv("DB_USER"),
        Password:      os.Getenv("DB_PASSWORD"),
        MigrationsDir: "./db/migrations",
        SSLMode:       "require",
    }

    if err := cfg.Validate(); err != nil {
        log.Fatalf("invalid config: %v", err)
    }

    engine, err := migrate.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer engine.Close()

    if err := engine.Up(); err != nil {
        log.Fatal(err)
    }
}

API reference

Package: config

Package: migrate

Sentinel errors