mofe/migrate repository overview

⁠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⁠?

⁠Databases

Database drivers run migrations. Add a new database?⁠

• PostgreSQL⁠
• Redshift⁠
• Ql⁠
• Cassandra⁠
• SQLite⁠ (todo #165⁠)
• MySQL/ MariaDB⁠
• Neo4j⁠ (todo #167⁠)
• MongoDB⁠ (todo #169⁠)
• CrateDB⁠ (todo #170⁠)
• Shell⁠ (todo #171⁠)
• Google Cloud Spanner⁠
• CockroachDB⁠
• ClickHouse⁠

⁠Migration Sources

Source drivers read migrations from local or remote sources. Add a new source?⁠

• Filesystem⁠ - read from fileystem
• Go-Bindata⁠ - read from embedded binary data (jteeuwen/go-bindata⁠)
• Github⁠ - read from remote Github repositories
• AWS S3⁠ - read from Amazon Web Services S3
• Google Cloud Storage⁠ - read from Google Cloud Platform Storage

⁠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 -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).
• Package migrate has no external dependencies.
• Only import the drivers you need. (check dependency_tree.txt⁠ for each driver)
• 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"
    _ "github.com/golang-migrate/migrate/database/postgres"
    _ "github.com/golang-migrate/migrate/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"
    "github.com/golang-migrate/migrate/database/postgres"
    _ "github.com/golang-migrate/migrate/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⁠.