mig

README

Dead simple Go migration tool and library that keeps your migrations inside a binary (or your application's own binary) for ease of use.

Install

go get -v github.com/erizocosmico/mig/...

Get started

First thing we should do is the following:

• Go to the root of your project
• Run mkdir migrations
• Run mig scaffold --db postgres (you can change postgres for any of the supported database drivers)

By now we'll have something like this:

| myproject/
    |- migrations/
    |- cmd/
        |- migrate/
            |- main.go

That migrate command is the binary we'll use to manage our migrations. Note that we didn't have to configure anything in the scaffold command other than the database because we used the default ./migrations as the package for our migrations.

Now we can start writing our migrations.

mig new initial_schema
mig new add_sessions_table
mig new add_profile_picture_column

That command will add new migration files inside the migrations directory.

You can edit them and place your migrations. It's Go code, so you can do whatever thing you want in there.

The migration files generated will look like this:

package migrations

import "github.com/erizocosmico/mig"

func main() {
        mig.Register(
                func(db mig.DB) error {
                        // your up code
                },
                func(db mig.DB) error {
                        // your down code
                },
        )
}

You will be thinking "do I have to make all the execs and if err != nil by hand?". No! mig's got you covered! There are some utility functions mig.ExecAll and mig.DropAll that should cover almost all your use cases. Check them out in the documentation.

Now, to execute you can run the generated command or build it and use it as a binary.

go ./cmd/migrate/main.go --help

or (assuming your ~/$GOPATH/bin is in your PATH)

go install ./cmd/migrate/...
migrate --help

There are 3 commands available in the migration manager:

• up runs all the migrations.
• rollback executes the down for the current version, leaving the database in the previous state e.g. if database is in version 3, this would get it to version 2.
• to-version get the database to a specific version.

migrate up --url postgres://postgres:@0.0.0.0:5432/testing?sslmode=disable

You can pass the URL as an environment variable as well:

DBURL=postgres://postgres:@0.0.0.0:5432/testing?sslmode=disable migrate to-version 5

Using the API programmatically

Lucky for you, the API can be used programmatically as well. Do you want to import your migrations? Easy, import them, it's just Go code.

package main

import (
        _ "my/package/migrations"
)

// do something

Check the documentation to see the list of available functionality, which is the same that is available using the generated command.

Why could this be useful? In case you want your binary to autoupdate itself accordingly. The downside of this is that all migrations code would be inside your main binary. That's why the mig tool scaffolds a separate command just for migration management.

Supported drivers

• MySQL
• PostgreSQL
• MSSQL
• SQLite3

Acknowledgements

go-pg/migrations for the inspiration. This library is basically migrations but it creates the migrations without needing to query the database or create the manager command yourself for the migrations. It also supports more databases than just PostgreSQL.

LICENSE

MIT, see LICENSE.

Documentation

Index

• func Create(path, name string) (string, error)
• func CurrentVersion(db *sql.DB) (version int64, err error)
• func Down(db *sql.DB, tx bool) (oldVersion, newVersion int64, err error)
• func DropAll(db DB, tables ...string) error
• func ExecAll(db DB, stmts ...string) error
• func Register(up, down MigrationFunc)
• func SetTableName(name string)
• func SetVersion(db DB, v int64) error
• func ToVersion(db *sql.DB, tx bool, v int64) (oldVersion, newVersion int64, err error)
• func Up(db *sql.DB, tx bool) (oldVersion, newVersion int64, err error)
• type DB
• type MigrationFunc

Functions

func Create

func Create(path, name string) (string, error)

Create creates a new migration file.

func CurrentVersion

func CurrentVersion(db *sql.DB) (version int64, err error)

CurrentVersion returns the current version of the database.

func Down

func Down(db *sql.DB, tx bool) (oldVersion, newVersion int64, err error)

Down rolls back a single database migration. If tx is true, all migrations will be run inside a transaction.

func DropAll

func DropAll(db DB, tables ...string) error

DropAll is an utility function to drop all tables in the given order.

DropAll(db, `baz`, `bar`, `foo`)

func ExecAll

func ExecAll(db DB, stmts ...string) error

ExecAll is an utility function to execute all the given migrations. This is specially useful for running a bunch of create tables and so on.

ExecAll(db,
	`CREATE TABLE foo ( ... )`,
	`CREATE TABLE bar ( ... )`,
	`CREATE TABLE baz ( ... )`,
)

func Register

func Register(up, down MigrationFunc)

Register adds a new migration. Its order will depend on the name of the file calling this function. For example, a file named 00001_initial_migration.go will be executed before a migration defined in 000004_add_users_table.go. Register needs to provide both an up and a down function.

func SetTableName

func SetTableName(name string)

SetTableName sets the name of the table used to store the migrations information in your database.

func SetVersion

func SetVersion(db DB, v int64) error

SetVersion sets the current version of the database to the given version.

func ToVersion

func ToVersion(db *sql.DB, tx bool, v int64) (oldVersion, newVersion int64, err error)

ToVersion executes up or down migrations from the current version until the target version. If tx is true, all migrations will be run inside a transaction.

func Up

func Up(db *sql.DB, tx bool) (oldVersion, newVersion int64, err error)

Up runs all the pending database migrations until it's up to date. If tx is true, all migrations will be run inside a transaction.

Types

type DB

type DB interface {
	Exec(query string, args ...interface{}) (sql.Result, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
}

DB is an interface that both a database instance and a transaction satisfy. It should be able to execute and perform queries.

type MigrationFunc

type MigrationFunc func(DB) error

MigrationFunc is a function that receives a database instance and runs a migration, either an up or a down.