Commits

Liam Staskawicz committed 2454507

readme: prelim usage notes

Comments (0)

Files changed (1)

 
 You can manage your database's evolution by creating incremental SQL (or, soon, Go) scripts.
 
-## Install
+# Install
 
     $ go get bitbucket.org/liamstask/goose
     $ go build -o bin/goose bitbucket.org/liamstask/goose/cmd
     
-## Usage
+# Usage
 
-TODO
+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".
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.