Source

goose / README.md

goose

goose is a database migration tool.

You can manage your database's evolution by creating incremental SQL (or, soon, Go) scripts.

Install

$ go get bitbucket.org/liamstask/goose
$ go build -o bin/goose bitbucket.org/liamstask/goose/cmd

Usage

goose expects you to maintain a folder (typically called "db"), which contains the following:

  • a dbconf.yml file that describes the database configurations you'd like to use
  • a folder called "migrations" which contains .sql and/or .go scripts that implement your migrations

Migrations

goose supports migrations written in SQL or in Go.

SQL Migrations

A sample SQL migration looks like:

-- +goose Up
CREATE TABLE post (
    id int NOT NULL,
    title text,
    body text,
    PRIMARY KEY(id)
);

-- +goose Down
DROP TABLE post;

Notice the annotations in the comments. Any statements following -- +goose Up will be executed as part of a forward migration, and any statements following -- +goose Down will be executed as part of a rollback.

Go Migrations

A sample Go migration looks like:

::: go
package migration_003

import (
    "database/sql"
    "fmt"
)

func Up(txn *sql.Tx) {
    fmt.Println("Hello from migration_003 Up!")
}

func Down(txn *sql.Tx) {
    fmt.Println("Hello from migration_003 Down!")
}

Up() will be executed as part of a forward migration, and Down() will be executed as part of a rollback.

A transaction is provided, rather than the DB instance directly, since we also need to record the schema version within the same transaction. Each migration should run as a single transaction anyway to ensure DB integrity, so it's good practice anyway.

Database Configurations

A sample dbconf.yml looks like

development:
    driver: postgres
    open: user=liam dbname=tester sslmode=disable

Here, 'development' specifies the name of the configuration, and the 'driver' and 'open' elements are passed directly to database/sql to access the specified database.

You may include as many configurations as you like, and you can use the --config command line option to specify which one to use. goose defaults to using a configuration called "development".