mirror of https://github.com/pressly/goose.git
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# 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`.
|