Examples structure refactor

.travis.yml

@@ -10,12 +10,12 @@ install:
 script:
 - go test
 - go build -i -o goose ./cmd/goose
-- ./goose -dir=example/migrations sqlite3 sql.db up
-- ./goose -dir=example/migrations sqlite3 sql.db version
-- ./goose -dir=example/migrations sqlite3 sql.db down
-- ./goose -dir=example/migrations sqlite3 sql.db status
-- go build -i -o custom-goose ./example/migrations-go
-- ./custom-goose -dir=example/migrations-go sqlite3 go.db up
-- ./custom-goose -dir=example/migrations-go sqlite3 go.db version
-- ./custom-goose -dir=example/migrations-go sqlite3 go.db down
-- ./custom-goose -dir=example/migrations-go sqlite3 go.db status
+- ./goose -dir=examples/sql-migrations sqlite3 sql.db up
+- ./goose -dir=examples/sql-migrations sqlite3 sql.db version
+- ./goose -dir=examples/sql-migrations sqlite3 sql.db down
+- ./goose -dir=examples/sql-migrations sqlite3 sql.db status
+- go build -i -o custom-goose ./examples/go-migrations
+- ./custom-goose -dir=examples/go-migrations sqlite3 go.db up
+- ./custom-goose -dir=examples/go-migrations sqlite3 go.db version
+- ./custom-goose -dir=examples/go-migrations sqlite3 go.db down
+- ./custom-goose -dir=examples/go-migrations sqlite3 go.db status

README.md

@@ -1,23 +1,30 @@
 # goose
 
-Goose is a database migration tool. Manage your database's evolution by creating incremental SQL files or Go functions.
+Goose is a database migration tool. Manage your database schema by creating incremental SQL changes or Go functions.
 
 [![GoDoc Widget]][GoDoc] [![Travis Widget]][Travis]
 
 ### Goals of this fork
 
-github.com/pressly/goose is a fork of bitbucket.org/liamstask/goose with the following changes:
+`github.com/pressly/goose` is a fork of `bitbucket.org/liamstask/goose` with the following changes:
 - No config files
 - [Default goose binary](./cmd/goose/main.go) can migrate SQL files only
 - Go migrations:
-    - We dropped building Go migrations on-the-fly from .go source files
-    - Instead, you can create your own goose binary, import `github.com/pressly/goose`
-      package and run complex Go migrations with your own `*sql.DB` connection
-    - Each Go migration function is called with `*sql.Tx` argument - within its own transaction
-- The goose pkg is decoupled from the default binary:
-    - goose pkg doesn't register any SQL drivers anymore
-      (no driver `panic()` conflict within your codebase!)
+    - We don't `go build` Go migrations functions on-the-fly
+      from within the goose binary
+    - Instead, we let you
+      [create your own custom goose binary](examples/go-migrations),
+      register your Go migration functions explicitly and run complex
+      migrations with your own `*sql.DB` connection
+    - Go migration functions let you run your code within
+      an SQL transaction, if you use the `*sql.Tx` argument
+- The goose pkg is decoupled from the binary:
+    - goose pkg doesn't register any SQL drivers anymore,
+      thus no driver `panic()` conflict within your codebase!
     - goose pkg doesn't have any vendor dependencies anymore
+- We encourage using sequential versioning of migration files
+    (rather than timestamps-based versioning) to prevent version
+    mismatch and migration colissions
 
 # Install
 
@@ -193,7 +200,7 @@ language plpgsql;
 
 ## Go Migrations
 
-1. Create your own goose binary, see [example](./example/migrations-go/cmd/main.go)
+1. Create your own goose binary, see [example](./examples/go-migrations)
 2. Import `github.com/pressly/goose`
 3. Register your migration functions
 4. Run goose command, ie. `goose.Up(db *sql.DB, dir string)`

examples/README.md

@@ -0,0 +1,2 @@
+# 1. [SQL migrations](sql-migrations)
+# 2. [Go migrations](go-migrations)

example/migrations/README.md → examples/sql-migrations/README.md

@@ -1,6 +1,6 @@
 # SQL migrations only
 
-See [second example](../migrations-go) for Go migrations.
+See [this example](../go-migrations) for Go migrations.
 
 ```bash
 $ go get -u github.com/pressly/goose/cmd/goose