# goose

goose is a database migration tool.

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

# Install

    $ go get bitbucket.org/liamstask/goose

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

# 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

You may use the `--db` option to specify an alternate location for the folder containing your config and 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 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.

## 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`.