goose is a database migration tool.

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

$ go get github.com/simonz05/goose/cmd/goose

This will install the goose binary to your $GOPATH/bin directory.

You can also build goose into your own applications by importing github.com/simonz05/goose/lib/goose. Documentation is available at godoc.org.

NOTE: the API is still new, and may undergo some changes.

goose provides several commands to help manage your database schema.

Create a new migration script.

$ goose create AddSomeColumns
$ goose: created db/migrations/20130106093224_AddSomeColumns.go

Edit the newly created script to define the behavior of your migration.

You can also create an SQL migration:

$ goose create AddSomeColumns sql
$ goose: created db/migrations/20130106093224_AddSomeColumns.sql

Apply all available migrations.

$ goose up
$ goose: migrating db environment 'development', current version: 0, target: 3
$ OK    001_basics.sql
$ OK    002_next.sql
$ OK    003_and_again.go

Roll back a single migration from the current version.

$ goose down
$ goose: migrating db environment 'development', current version: 3, target: 2
$ OK    003_and_again.go

Roll back the most recently applied migration, then run it again.

$ goose redo
$ goose: migrating db environment 'development', current version: 3, target: 2
$ OK    003_and_again.go
$ goose: migrating db environment 'development', current version: 2, target: 3
$ OK    003_and_again.go

Print the status of all migrations:

$ goose status
$ goose: status for environment 'development'
$   Applied At                  Migration
$   =======================================
$   Sun Jan  6 11:25:03 2013 -- 001_basics.sql
$   Sun Jan  6 11:25:03 2013 -- 002_next.sql
$   Pending                  -- 003_and_again.go

Print the current version of the database:

$ goose dbversion
$ goose: dbversion 002

goose -h provides more detailed info on each command.

goose supports migrations written in SQL or in Go.

A sample SQL migration looks like:

:::sql
-- +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.

By default, SQL statements are delimited by semicolons - in fact, query statements must end with a semicolon to be properly recognized by goose.

More complex statements (PL/pgSQL) that have semicolons within them must be annotated with -- +goose StatementBegin and -- +goose StatementEnd to be properly recognized. For example:

:::sql
-- +goose Up
-- +goose StatementBegin
CREATE OR REPLACE FUNCTION histories_partition_creation( DATE, DATE )
returns void AS $$
DECLARE
  create_query text;
BEGIN
  FOR create_query IN SELECT
      'CREATE TABLE IF NOT EXISTS histories_'
      || TO_CHAR( d, 'YYYY_MM' )
      || ' ( CHECK( created_at >= timestamp '''
      || TO_CHAR( d, 'YYYY-MM-DD 00:00:00' )
      || ''' AND created_at < timestamp '''
      || TO_CHAR( d + INTERVAL '1 month', 'YYYY-MM-DD 00:00:00' )
      || ''' ) ) inherits ( histories );'
    FROM generate_series( $1, $2, '1 month' ) AS d
  LOOP
    EXECUTE create_query;
  END LOOP;  -- LOOP END
END;         -- FUNCTION END
$$
language plpgsql;
-- +goose StatementEnd

A sample Go migration looks like:

:::go
package main

import (
    "database/sql"
    "fmt"
)

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

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

Up_20130106222315() will be executed as part of a forward migration, and Down_20130106222315() will be executed as part of a rollback.

The numeric portion of the function name (20130106222315) must be the leading portion of migration's filename, such as 20130106222315_descriptive_name.go. goose create does this by default.

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

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

You may use the -path option to specify an alternate location for the folder containing your config and migrations.

In cases when your migrations and configurations are stored in the separate locations (i.e. migrations are checked out from the repository and configuration file is generated during the deployment) you are able to specify this using -path and -conf options. Examples of different cases are provided below:

// By default goose will try to open /path/to/app/db/dbconf.yml and will use
// /path/to/app/db/migrations for migrations
$ goose -path=/path/to/app/db status

// In this case goose will try to open /path/to/app/db/db.yml (looks relatively to `path`)
$ goose -path=/path/to/app/db -conf=db.yml status

// Here goose will try to open /path/to/etc/db.yml and will use
// /path/to/app/db/migrations for migrations
$ goose -path=/path/to/app/db -conf=/path/to/etc/db.yml status

// And here goose will try to open mydb.yml using specified path relatively to the current working directory
$ goose -path=/path/to/app/db -conf=../../relative/mydb.yml status

A sample dbconf.yml looks like

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

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

You may include as many environments as you like, and you can use the -env command line option to specify which one to use. goose defaults to using an environment called development.

goose will expand environment variables in the open element. For an example, see the Heroku section below.

goose knows about some common SQL drivers, but it can still be used to run Go-based migrations with any driver supported by database/sql. An import path and known dialect are required.

Currently, available dialects are: "postgres", "mysql", or "sqlite3"

To run Go-based migrations with another driver, specify its import path and dialect, as shown below.

customdriver:
    driver: custom
    open: custom open string
    import: github.com/custom/driver
    dialect: mysql

NOTE: Because migrations written in SQL are executed directly by the goose binary, only drivers compiled into goose may be used for these migrations.

These instructions assume that you're using Keith Rarick's Heroku Go buildpack. First, add a file to your project called (e.g.) install_goose.go to trigger building of the goose executable during deployment, with these contents:

// use build constraints to work around http://code.google.com/p/go/issues/detail?id=4210
// +build heroku

// note: need at least one blank line after build constraint
package main

import _ "github.com/simonz05/goose/cmd/goose"

Set up your Heroku database(s) as usual.

Then make use of environment variable expansion in your dbconf.yml:

production:
    driver: postgres
    open: $DATABASE_URL

To run goose in production, use heroku run:

heroku run goose -env production up

Thank you!

• Josh Bleecher Snyder (josharian)
• Abigail Walthall (ghthor)
• Daniel Heath (danielrheath)
• Chris Baynes (chris_baynes)
• Michael Gerow (gerow)
• Vytautas Šaltenis (rtfb)
• James Cooper (coopernurse)
• Gyepi Sam (gyepisam)
• Matt Sherman (clipperhouse)
• runner_mei
• John Luebs (jkl1337)
• Luke Hutton (lukehutton)