Database migrations. CLI and Golang library.
Go to file
Dale Hui 16197b67e3 Update to golangci-lint v1.16.0
- Fix newly raised issues
2019-04-07 00:51:27 -07:00
.github/ISSUE_TEMPLATE Add Go version to but report template 2018-09-19 03:10:08 -07:00
cli Add guide for installing a specific version of `migrate` using the Go toolchain 2018-11-28 01:00:46 -08:00
cmd/migrate Copy cli main package under migrate directory, keep deprecated original main package for backwards compatibility, fixes #70 2018-11-21 09:01:35 +01:00
database Update to golangci-lint v1.16.0 2019-04-07 00:51:27 -07:00
dktesting Update dktest from v0.2.0 to v0.3.0 2019-01-08 22:39:26 -08:00
internal/cli Fixes for unused linter 2019-03-22 22:08:29 +03:00
source Fixes for govet 2019-03-22 23:05:19 +03:00
testing Update golangci-lint config and implore contributors to use it 2019-03-28 18:55:12 -07:00
.dockerignore add dockerization Fix #23 2018-05-09 09:48:20 +02:00
.gitignore Ignore vendor dir 2018-01-19 10:57:17 -08:00
.golangci.yml Update golangci-lint config and implore contributors to use it 2019-03-28 18:55:12 -07:00
.travis.yml Update to golangci-lint v1.16.0 2019-04-07 00:51:27 -07:00
CONTRIBUTING.md Remove spurious list item 2019-03-28 21:35:54 -07:00
Dockerfile Gitlab source (#184) 2019-03-10 18:38:23 -07:00
FAQ.md Update FAQ.md 2018-12-14 16:28:04 +00:00
LICENSE Update copyright in LICENSE 2018-11-08 01:45:19 -08:00
MIGRATIONS.md Link to comparison of transactional DDLs 2018-07-09 19:25:29 -07:00
Makefile Include firebird db driver in default builds 2019-04-05 23:25:57 -07:00
README.md List Gitlab as a supported source 2019-03-21 01:54:59 -07:00
docker-deploy.sh Add latest tag to docker image during build 2018-07-03 14:09:26 -07:00
go.mod Added Firebird support (#191) 2019-03-21 01:51:49 -07:00
go.sum Added Firebird support (#191) 2019-03-21 01:51:49 -07:00
log.go add some more comments 2017-02-09 18:23:08 -08:00
migrate.go Added misspell linter 2019-03-22 23:57:00 +03:00
migrate_test.go Update golangci-lint config and implore contributors to use it 2019-03-28 18:55:12 -07:00
migration.go fix old ref to LogString 2017-02-09 18:26:58 -08:00
migration_test.go rename Migration.LongString to LogString 2017-02-09 18:06:38 -08:00
util.go Fmt (#189) 2019-03-13 12:15:21 -07:00
util_test.go Improve error output for missing or malformed '-database' and '-source' parameters 2018-08-08 21:27:12 +02:00

README.md

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

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.

Forked from mattes/migrate

Databases

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:password@host:port/dbname?option1=true&option2=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!#$%&'()*+,/:;=?@[]
FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D
$ python2 -c 'import urllib; print urllib.quote(raw_input("String to encode: "), "")'
String to encode: FAKEpassword!#$%&'()*+,/:;=?@[]
FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D
$

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 io.Reader streams internally for low memory overhead.
  • Thread-safe and no goroutine leaks.

Go Documentation

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

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.

Versions

Version Supported? Import Notes
master import "github.com/golang-migrate/migrate/v4" New features and bug fixes arrive here first
v4 import "github.com/golang-migrate/migrate/v4" Used for stable releases
v3 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! Makefile is your friend, read the development guide.

Also have a look at the FAQ.


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