migrate README

The project's README from github.com/golang-migrate/migrate. As one markdown file: README.md.

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.

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

CLI Documentation (includes CLI install instructions)

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

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.Up() // or m.Steps(2) if you want to explicitly set the number of migrations to run
}

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.

Coming from another db migration tool?

Check out migradaptor. Note: migradaptor is not affiliated or supported by this project

Versions

Version Supported? Import Notes
master :white_check_mark: import "github.com/golang-migrate/migrate/v4" New features and bug fixes arrive here first
v4 :white_check_mark: 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.

migrate (golang-migrate/migrate)

Searching Database…

19K ·GitHub
Migrate
What is this?A database migration tool written in Go: it reads migrations from a source (files, S3, GitHub, etc.) and applies them in the correct order to your database. Use it as a CLI or import it as a Go library.
Is it a tool I install, or a library I import into my Go code?Both. The CLI is a thin wrapper around the same library, while Go projects import github.com/golang-migrate/migrate/v4 via Go modules — the v3/v4 API is stable and frozen.
How do I get it running?Install the CLI (see the CLI documentation for install instructions), run it as a Docker container, or import github.com/golang-migrate/migrate/v4 via Go modules. Getting-started guides and tutorials for PostgreSQL and CockroachDB are linked.
Which databases does it support?PostgreSQL (plus PGX v4/v5), MySQL/MariaDB, SQLite and SQLCipher, MS SQL Server, MongoDB, Cassandra/ScyllaDB, Neo4j, ClickHouse, CockroachDB, Google Cloud Spanner and more — a few drivers like CrateDB and Shell are still marked todo.
Are there any gotchas with connection strings?Connections are specified as URLs (dbdriver://user:password@host:port/dbname), and reserved characters — including % — must be escaped; the README suggests URL-encoding every part of the connection URL.
Why does the README call the database drivers 'dumb'?The drivers deliberately assume nothing and never try to correct user input — when in doubt, they fail. Migrate itself glues everything together and keeps the logic bulletproof, which also keeps the drivers lightweight.
Can I run the CLI in Docker?Yes — Docker usage is documented in the README, and the repository ships a Dockerfile with CI workflows for builds and releases.
I'm switching from another migration tool — is there help?The README points to migradaptor for coming from another db migration tool, with the caveat that it is not affiliated with or supported by this project.
What are similar projects?goose, usql, flyway, beekeeper-studio, typeorm, TablePro, orm, dbx
Which topics is it in?cassandra, google-cloud-storage, databases, migration, neo4j, mariadb, postgres, mongodb, mysql, sql, golang, sqlite
Creator
golang-migrate
Size
2.4 MB
Stars
19K
Updated
CommitSep 09Releasev4.20.1Sep 09
Age
8y
Commits · 90 Days