⚡ GoMigrate

Beautiful, interactive database migrations for Go developers

A friendly wrapper around golang-migrate with short commands, YAML config, and a polished terminal UI.

go install github.com/taqnihub/gomigrate@latest

---

🚀 Quick Start

# 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 files)
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

That's it. No Docker commands. No 200-character invocations. Just works.

---

✨ Why GoMigrate?

Database migrations don't have to be painful. Compare:

Before — raw golang-migrate:

docker run -it --rm --network host --volume ./db:/db \
  migrate/migrate:v4.19.0 \
  -path=/db/migrations \
  -database "mysql://root:password@localhost:3306/ecomm" \
  up

After — gomigrate:

gomigrate up

Features

• 🎨 Beautiful output — colored, styled, easy to read
• 🖥️ Interactive TUI — run gomigrate with no args for a menu
• 📝 YAML config — .gomigrate.yml keeps credentials out of shell history
• 🔐 Env var support — override any setting with GOMIGRATE_* variables
• 🛡️ Safety first — duplicate detection, dirty-state recovery, clear errors
• 📦 Library mode — import github.com/taqnihub/gomigrate in your Go code
• 🐬 🐘 MySQL & PostgreSQL — full support for both

---

📥 Installation

Install the CLI

With Go 1.22+ installed, one command:

go install github.com/taqnihub/gomigrate@latest

Verify it works:

gomigrate --version

Note: Make sure $(go env GOPATH)/bin is in your $PATH. Add this to your shell config if gomigrate isn't found after install:

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

Use as a Go library

Add GoMigrate to your Go project:

go get github.com/taqnihub/gomigrate@latest

Then import in your code:

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

See Library Usage below for full examples.

For contributors

Only needed if you want to modify the code or submit a PR:

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

---

📖 CLI Usage

Interactive mode

Just run gomigrate with no arguments:

gomigrate

You'll get a menu to navigate with arrow keys.

All commands at a glance

Command	Description	Example
gomigrate	Launch interactive TUI menu	gomigrate
gomigrate init	Interactive wizard to create .gomigrate.yml	gomigrate init
gomigrate init --force	Overwrite existing config	gomigrate init --force
gomigrate create <name>	Generate up/down SQL files	gomigrate create add_users_table
gomigrate up	Apply all pending migrations	gomigrate up
gomigrate up [n]	Apply the next N migrations	gomigrate up 3
gomigrate down	Revert the last migration	gomigrate down
gomigrate down [n]	Revert the last N migrations	gomigrate down 2
gomigrate down --all	Revert ALL applied migrations (destructive)	gomigrate down --all
gomigrate status	Show applied vs pending migrations	gomigrate status
gomigrate force <version>	Reset migration version (fix dirty state)	gomigrate force 20260417103045
gomigrate --version	Show gomigrate version	gomigrate --version
gomigrate --help	Show help for all commands	gomigrate --help
gomigrate <cmd> --help	Show help for a specific command	gomigrate up --help

Global flags (work with any command)

Flag	Short	Description	Example
--config <path>	-c	Path to config file	gomigrate -c ./prod.yml up
--driver <name>	-d	Override database driver	gomigrate -d postgres status
--dir <path>		Override migrations directory	gomigrate --dir ./db/migs up
--verbose	-v	Show detailed output	gomigrate -v up
--no-interactive		Disable TUI & colors (CI-friendly)	gomigrate --no-interactive up

---

🔧 Configuration

GoMigrate reads config from (in priority order):

1. CLI flags (--driver mysql, --dir ./migrations, etc.)
2. Environment variables (GOMIGRATE_*)
3. .gomigrate.yml in the current directory
4. .gomigrate.yml in your home directory
5. Sensible defaults

Config file

.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

Environment variables

Perfect for CI/CD:

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

gomigrate up

---

📚 Library Usage

GoMigrate is also a Go library. Import it in your code:

package main

import (
    "log"

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

func main() {
    // Load config from .gomigrate.yml or env vars
    cfg, err := config.Load("")
    if err != nil {
        log.Fatal(err)
    }

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

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

    // Check current version
    version, dirty, _ := engine.Version()
    log.Printf("at version %d (dirty: %v)", version, dirty)
}

Common use case: auto-migrate on app startup

func main() {
    cfg, _ := config.Load("")
    engine, _ := migrate.New(cfg)
    defer engine.Close()

    // Auto-apply pending migrations when the app starts
    if err := engine.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
        log.Fatal("migration failed:", err)
    }

    // ... start your web server ...
}

---

📝 Writing Migrations

Migration files are plain SQL. GoMigrate creates pairs of files:

db/migrations/
├── 20260417100000_add_users_table.up.sql
└── 20260417100000_add_users_table.down.sql

up.sql — apply the change:

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

down.sql — undo the change:

DROP TABLE IF EXISTS users;

Naming conventions

Pattern	Example
create_<table>_table	create_users_table
add_<column>_to_<table>	add_email_to_users
drop_<column>_from_<table>	drop_legacy_id_from_orders
add_index_<n>	add_index_email_to_users

---

🆚 Comparison

Feature	gomigrate	golang-migrate CLI	goose
Interactive TUI	✅	❌	❌
YAML config file	✅	❌	❌
Env var support	✅	❌	✅
Pretty colored output	✅	❌	⚠️
Duplicate detection	✅	❌	❌
Library mode	✅	✅	✅
MySQL support	✅	✅	✅
PostgreSQL support	✅	✅	✅

---

🛠️ Development (for contributors)

Prerequisites

• Go 1.22 or higher
• MySQL or PostgreSQL (for testing)

Clone and build

git clone https://github.com/taqnihub/gomigrate.git
cd gomigrate
go mod download
make build

Available commands

make build        # Build the binary
make test         # Run unit tests
make test-cover   # Run tests with coverage report
make install      # Install to $GOPATH/bin
make clean        # Remove build artifacts

Project structure

gomigrate/
├── cmd/           # Cobra CLI commands
├── config/        # Config loading (public library package)
├── migrate/       # Migration engine (public library package)
├── internal/tui/  # TUI components (private)
└── main.go        # CLI entry point

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Add tests
5. Run make test to verify
6. Commit with conventional messages (feat:, fix:, docs:, etc.)
7. Push and open a PR

Reporting issues

Found a bug? Have a feature request? Open an issue.

---

📄 License

MIT © taqnihub

---

🙏 Credits

Built with:

• golang-migrate — the powerful migration engine under the hood
• cobra — CLI framework
• viper — config management
• bubbletea — TUI framework
• lipgloss — terminal styling
• huh — interactive forms

If gomigrate saves you time, consider giving it a ⭐ on GitHub!