by golang-migrate

golang-migrate / migrate

Database migrations. CLI and Golang library.

5.2K Stars 536 Forks Last release: 29 days ago (v4.13.0) Other 1.0K Commits 50 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Build Status GoDoc Coverage Status packagecloud.io Docker Pulls Supported Go Versions GitHub Release Go Report Card


Database migrations written in Go. Use as CLI or import as library.

  • Migrate reads migrations from sources and applies them in correct order to a database.
  • Drivers are "dumb", migrate glues everything together and makes sure the logic is bulletproof. (Keeps the drivers lightweight, too.)
  • Database drivers don't assume things or try to correct user input. When in doubt, fail.

Forked from mattes/migrate


Database drivers run migrations. Add a new database?

Database URLs

Database connection strings are specified via URLs. The URL format is driver dependent but generally has the form:

dbdriver://username:[email protected]:port/dbname?param1=true&param2=false

Any reserved URL characters need to be escaped. Note, the

character also needs to be escaped

Explicitly, the following characters need to be escaped:


It's easiest to always run the URL parts of your DB connection URL (e.g. username, password, etc) through an URL encoder. See the example Python snippets below:

$ python3 -c 'import urllib.parse; print(urllib.parse.quote(input("String to encode: "), ""))'
String to encode: FAKEpassword!#$%&'()*+,/:;[email protected][]
$ python2 -c 'import urllib; print urllib.quote(raw_input("String to encode: "), "")'
String to encode: FAKEpassword!#$%&'()*+,/:;[email protected][]

Migration Sources

Source drivers read migrations from local or remote sources. Add a new source?

CLI usage

  • Simple wrapper around this library.
  • Handles ctrl+c (SIGINT) gracefully.
  • No config search paths, no config files, no magic ENV var injections.

CLI Documentation

Basic usage

$ migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2

Docker usage

$ docker run -v {{ migration dir }}:/migrations --network host migrate/migrate
    -path=/migrations/ -database postgres://localhost:5432/database up 2

Use in your Go project

  • API is stable and frozen for this release (v3 & v4).
  • Uses Go modules to manage dependencies.
  • To help prevent database corruptions, it supports graceful stops via
    GracefulStop chan bool
  • Bring your own logger.
  • Uses
    streams internally for low memory overhead.
  • Thread-safe and no goroutine leaks.

Go Documentation

import (
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/github"

func main() { m, err := migrate.New( "github://mattes:[email protected]/migrate_test", "postgres://localhost:5432/database?sslmode=enable") m.Steps(2) }

Want to use an existing database client?

import (
    _ "github.com/lib/pq"
    _ "github.com/golang-migrate/migrate/v4/source/file"

func main() { db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable") driver, err := postgres.WithInstance(db, &postgres.Config{}) m, err := migrate.NewWithDatabaseInstance( "file:///migrations", "postgres", driver) m.Steps(2) }

Getting started

Go to getting started


(more tutorials to come)

Migration files

Each migration has an up and down migration. Why?


Best practices: How to write migrations.



Supported? Import Notes
master :whitecheckmark:

import "github.com/golang-migrate/migrate/v4"
New features and bug fixes arrive here first
v4 :whitecheckmark:
import "github.com/golang-migrate/migrate/v4"
Used for stable releases
v3 :x:
import "github.com/golang-migrate/migrate"
(with package manager) or
import "gopkg.in/golang-migrate/migrate.v3"
(not recommended)
DO NOT USE - No longer supported

Development and Contributing

Yes, please!

is your friend, read the development guide.

Also have a look at the FAQ.

Looking for alternatives? https://awesome-go.com/#database.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.