migrate

migrate is a Go library and CLI for running database schema migrations. It reads versioned migration files from a source driver (local filesystem, embedded Go io/fs, S3, GitHub, GitLab, Bitbucket, or Google Cloud Storage) and applies them in order to a database driver, with support for 20+ databases including PostgreSQL, MySQL, SQLite, MongoDB, Cassandra, ClickHouse, and Google Cloud Spanner.

The core package stays deliberately “dumb”: migration logic — ordering, locking, dirty-state tracking, graceful stop — lives entirely in the top-level package, while source and database drivers implement narrow interfaces and register themselves via init(). This keeps individual drivers small and interchangeable, and lets teams embed migrate directly in their own Go binaries via WithInstance() using an already-open database connection, rather than shelling out to a separate CLI.

What You Get

• Go library import (github.com/golang-migrate/migrate/v4) with New(), NewWithDatabaseInstance(), and WithInstance() constructors for embedding in Go programs
• Standalone migrate CLI binary, also published as a Docker image, for running migrations outside your application code
• Database drivers for 20+ engines, each implementing the same database.Driver interface so migration files stay portable across backends
• Source drivers for local files, embedded Go io/fs, and remote GitHub, GitLab, Bitbucket, AWS S3, and Google Cloud Storage locations
• Built-in dirty-state detection, advisory locking, and a Force() escape hatch for manual recovery after a failed migration

Common Use Cases

• Running schema migrations automatically at application startup via WithInstance()
• Applying migrations as a CI/CD deployment step using the CLI or the published Docker image
• Keeping the same migration files portable across multiple supported database engines (e.g. Postgres in production, SQLite locally)
• Storing and applying migrations from a remote source (S3, GitHub, GCS) instead of bundling files into every deploy artifact

Under The Hood

Architecture

migrate centers on two narrow, well-documented interfaces — source.Driver and database.Driver — with all migration orchestration (version ordering, locking, dirty-state tracking, graceful stop via a GracefulStop channel) kept in the top-level migrate package so individual drivers stay “dumb” and interchangeable. Drivers self-register into a package-level map via init(), and the CLI binary (cmd/migrate, backed by internal/cli) composes only the drivers selected through Go build tags at compile time, keeping any given binary’s dependency footprint scoped to the databases and sources it actually needs. This registry-plus-interface pattern is what lets 20+ database drivers and 10+ source drivers share one core without the core knowing any backend specifics.

Tech Stack

Built for Go 1.25+ using the standard database/sql package alongside native/CGo-free drivers per backend (lib/pq and jackc/pgx v4/v5 for Postgres, go-sql-driver/mysql, mattn/go-sqlite3 and modernc.org/sqlite for SQLite, gocql for Cassandra/ScyllaDB, mongo-driver for MongoDB, Google Cloud Spanner/Storage and AWS SDK clients for cloud backends, plus go-github, go-gitlab, and go-bitbucket for remote migration sources). The Makefile drives CGO_ENABLED=0 cross-platform builds gated by SOURCE/DATABASE build-tag lists, and the project ships Dockerfiles for both local and CI image builds plus prebuilt CLI binaries for major platforms.

Code Quality

The repository carries roughly 50 _test.go files, including shared database/testing and source/testing harnesses that every driver’s test suite calls into, so new drivers get the same correctness checks (Open/Close/Lock/Run behavior) without reimplementing them. Errors are explicit sentinel or typed values (ErrDirty, ErrLocked, ErrShortLimit) rather than swallowed, a .golangci.yml enforces lint rules, and GitHub Actions CI (ci.yaml) runs the suite on each change.

API Design The public surface is small and consistent: New()/NewWithDatabaseInstance()/WithInstance() constructors, then Up()/Down()/Steps()/Migrate()/Force() as the entire verb set, mirrored 1:1 by the CLI’s up/down/goto/force subcommands. Getting started with an existing *sql.DB requires only a WithInstance() call and a blank import for the chosen driver package — no config files or generated code — which keeps the boilerplate to embed migrate in an existing service low.