Database migrations. CLI and Golang library.
Go to file
Andrei Mackenzie 3373343f23 Remove advisory locking from the Redshift implementation
Redshift does not support advisory lock functions. The closest
capability is in-transaction table locks, which aren't quite right here
because the transaction scope is established within SetVersion, not
higher up above the Lock-before/Unlock-after SetVersion.

Local locking is left intact to satisfy expected "can't Lock twice
before Unlocking" behavior asserted in shared tests.
2018-11-03 18:31:41 -04:00
.github/ISSUE_TEMPLATE Add Go version to but report template 2018-09-19 03:10:08 -07:00
cli Clone the 'postgres' driver as 'redshift2' 2018-11-03 18:04:22 -04:00
database Remove advisory locking from the Redshift implementation 2018-11-03 18:31:41 -04:00
source Use v4 for Go module support 2018-10-10 16:16:23 -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 Revert "Remove support for Go modules" 2018-10-10 16:15:33 -07:00
CONTRIBUTING.md Remove references to `dep` from docs 2018-10-29 10:56:55 -07:00
Dockerfile Revert "Docker builds need to use dep to manage dependencies" 2018-10-10 16:16:23 -07:00
FAQ.md FAQ: add required extension 2017-07-28 14:30:10 +02: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 initial version 3.0.0 preview 2017-02-07 22:01:29 -08:00
MIGRATIONS.md Link to comparison of transactional DDLs 2018-07-09 19:25:29 -07:00
Makefile Clone the 'postgres' driver as 'redshift2' 2018-11-03 18:04:22 -04:00
README.md Remove references to `dep` from docs 2018-10-29 10:56:55 -07:00
docker-deploy.sh Add latest tag to docker image during build 2018-07-03 14:09:26 -07:00
go.mod Update dependencies 2018-10-15 13:26:18 -07:00
go.sum Update dependencies 2018-10-15 13:26:18 -07: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 v4 for Go module support 2018-10-10 16:16:23 -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 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.

Looking for v1?

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 helpers 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.x).
  • 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.

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.