Database migrations. CLI and Golang library.
Go to file
Dale Hui 600f2eda93 Fix broken build
- `gem install` no longer recognizes the `--no-ri` and `--no-rdoc` options. Use `--no-document` instead.
    - References:
        - https://github.com/rubygems/rubygems/pull/2354
        - https://github.com/bundler/bundler/pull/6624
2019-01-03 16:35:22 -08: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 Changed migrations table struct of field `version` to fix support `database.NilVersion` and default version format. 2018-12-28 15:53:55 +03:00
internal/cli 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
source use URL.Opaque when available 2018-12-20 15:08:49 -07:00
testing Remove unused invalid formatter 2018-01-21 02:04:36 -08: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
.travis.yml Fix broken build 2019-01-03 16:35:22 -08:00
CONTRIBUTING.md Remove references to `dep` from docs 2018-10-29 10:56:55 -07:00
Dockerfile 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
FAQ.md Update FAQ.md 2018-12-14 16:28:04 +00:00
Gopkg.lock Update dependencies 2018-10-15 13:26:18 -07:00
Gopkg.toml github.com/docker/docker package updated to api v1.37 2018-10-15 17:39:43 +03: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 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
README.md Add supported major versions table to README 2018-12-13 22:53:07 -08:00
docker-deploy.sh Add latest tag to docker image during build 2018-07-03 14:09:26 -07:00
go.mod Upgrade go-sql-driver/mysql to v1.4.1 2018-12-18 18:01:52 -05:00
go.sum Update docker/docker checksum for Go 1.11.4 2018-12-21 12:53:53 -08:00
log.go add some more comments 2017-02-09 18:23:08 -08:00
migrate.go Use v4 for Go module support 2018-10-10 16:16:23 -07:00
migrate_test.go Use strings.NewReader() instead of bytes.NewReader() when source is a string 2018-11-05 22:50:08 -08: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 Improve error output for missing or malformed '-database' and '-source' parameters 2018-08-08 21:27:12 +02: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.

Supported Major Versions

Version Go Modules Min Go Version Import Notes
master 1.10.3 import "github.com/golang-migrate/migrate/v4" New features and bug fixes arrive here first
v4 1.10.3 import "github.com/golang-migrate/migrate/v4"
v3 1.10 import "github.com/golang-migrate/migrate" (with package manager) or import "gopkg.in/golang-migrate/migrate.v3" (not recommended) Only security fixes are backported. Only use if your project is not using Go modules.

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.