Migrations with golang-migrate & goose

Schema changes belong in versioned migration files, not ad hoc ALTER in application startup.

golang-migrate and goose are popular Go-friendly tools that apply ordered SQL (or Go) migrations and support rollbacks in CI and deploy pipelines.

Summary

Migrations are timestamped or sequenced files with up and down sections.

Apply migrations before new code serves traffic, or use expand-contract patterns for zero-downtime deploys.

Run migration jobs in CI against ephemeral databases to catch SQL errors early.

Never run migrations inside per-request HTTP handlers.

Recipe

Quick-reference recipe card - copy-paste ready.

# golang-migrate CLI
migrate -path ./migrations -database "${DATABASE_URL}" up
migrate -path ./migrations -database "${DATABASE_URL}" down 1
 
# goose CLI
goose -dir ./migrations postgres "$DATABASE_URL" up
goose -dir ./migrations postgres "$DATABASE_URL" down

// embed migrations (see sibling article)
//go:embed migrations/*.sql
var migrationFS embed.FS

When to reach for this:

• Any team-managed SQL schema shared across environments.
• Deploy pipelines that must fail if schema drift exists.
• Rollback drills where down migrations restore prior shape in staging.

Working Example

package main
 
import (
    "database/sql"
    "fmt"
    "log"
 
    "github.com/pressly/goose/v3"
    _ "github.com/jackc/pgx/v5/stdlib"
)
 
func main() {
    db, err := sql.Open("pgx", "postgres://localhost:5432/app?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
 
    goose.SetDialect("postgres")
    if err := goose.Up(db, "migrations"); err != nil {
        log.Fatal(err)
    }
    fmt.Println("migrations applied")
}

Example migrations/00001_create_users.sql:

-- +goose Up
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL UNIQUE
);
 
-- +goose Down
DROP TABLE users;

What this demonstrates:

• goose.Up applies pending files in lexical order.
• Each file documents forward and reverse steps.
• SetDialect selects SQL quirks for Postgres, MySQL, or SQLite.
• Migration runs as a deploy hook or init container, not per HTTP request.

Deep Dive

How It Works

• Tools track applied versions in a metadata table (schema_migrations or goose version table).
• up runs pending files; down reverses the latest or N steps.
• golang-migrate names files 000001_init.up.sql and 000001_init.down.sql.
• goose supports SQL and Go migrations for data backfills that need loops.

CI and Deploy Flow

Zero-Downtime Patterns

1. Expand: add nullable column or new table; deploy code that writes both old and new.
2. Migrate data: backfill job outside request path.
3. Contract: remove old column after traffic uses new shape.

Breaking changes (NOT NULL without default, rename in place) need multi-phase releases.

golang-migrate vs goose

Gotchas

• Editing applied migration files - Environments diverge silently. Fix: new forward-only migration to correct state.
• Missing down migration - Rollback drills fail. Fix: require down in review for reversible changes; document irreversible ops.
• Long-running migration in deploy timeout - Deploy kills job mid-ALTER. Fix: run heavy migrations as separate maintenance job with lock monitoring.
• App startup AutoMigrate in prod - Race across replicas; untracked diffs. Fix: explicit migration job with version table.
• No CI database - Broken SQL reaches production. Fix: ephemeral Postgres service in pipeline applying up before tests.
• Destructive down in production - Data loss on rollback. Fix: treat down as staging-only; prod rollbacks restore backups.

Alternatives

FAQs

Related

• embed for SQL Migrations & Seed Data - bundle files in the binary
• Databases Basics - SQL execution basics
• Transactions, Prepared Statements & sql.Tx - DDL transaction limits
• GORM vs sqlx vs Raw database/sql - AutoMigrate trade-offs
• Databases & Data Access Best Practices - migration CI rules

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build). cGJxcnRodnFyZi52YnxwdHZiNDA3fDIwMjYwNw==