Need help with migrate?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

golang-migrate
7.4K Stars 780 Forks Other 1.1K Commits 137 Opened issues

Description

Database migrations. CLI and Golang library.

Services available

!
?

Need anything else?

Contributors list

GitHub Workflow Status (branch) GoDoc Coverage Status packagecloud.io Docker Pulls Supported Go Versions GitHub Release Go Report Card

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:[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][]
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!#$%&'()*+,/:;[email protected][]
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:[email protected]/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) }

Getting started

Go to getting started

Tutorials

(more tutorials to come)

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 :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!

Makefile
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.