migrate

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.

Looking for v1?

Databases

Database drivers run migrations. Add a new database?

Migration Sources

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

Filesystem - read from fileystem
Go-Bindata - read from embedded binary data (jteeuwen/go-bindata)
Github - read from remote Github repositories
AWS S3 - read from Amazon Web Services S3
Google Cloud Storage - read from Google Cloud Platform Storage

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 -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.x).
Package migrate has no external dependencies.
Only import the drivers you need. (check dependency_tree.txt for each driver)
To help prevent database corruptions, it supports graceful stops via GracefulStop chan bool.
Bring your own logger.
Uses io.Reader streams internally for low memory overhead.
Thread-safe and no goroutine leaks.

Go Documentation

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

func main() {
    m, err := migrate.New(
        "github://mattes:personal-access-token@mattes/migrate_test",
        "postgres://localhost:5432/database?sslmode=enable")
    m.Steps(2)
}

Want to use an existing database client?

import (
    "database/sql"
    _ "github.com/lib/pq"
    "github.com/golang-migrate/migrate"
    "github.com/golang-migrate/migrate/database/postgres"
    _ "github.com/golang-migrate/migrate/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)
}

Migration files

Each migration has an up and down migration. Why?

1481574547_create_users_table.up.sql
1481574547_create_users_table.down.sql

Best practices: How to write migrations.

Development and Contributing

Yes, please! Makefile is your friend, read the development guide.

Also have a look at the FAQ.

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

basekit/migrate