From 4df66b56ef8c03a35c8ccc5c6ce2c51302c09db0 Mon Sep 17 00:00:00 2001
From: Vojtech Vitek <vojtech.vitek@pressly.com>
Date: Tue, 20 Jun 2017 12:07:18 -0400
Subject: [PATCH] Add example READMEs

---
 example/migrations-go/README.md | 42 +++++++++++++++++++++++++++++++++
 example/migrations/README.md    | 26 ++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 example/migrations-go/README.md
 create mode 100644 example/migrations/README.md

diff --git a/example/migrations-go/README.md b/example/migrations-go/README.md
new file mode 100644
index 0000000..1ff883c
--- /dev/null
+++ b/example/migrations-go/README.md
@@ -0,0 +1,42 @@
+# SQL + Go migrations
+
+## Example custom goose binary with built-in Go migrations
+
+```bash
+$ go build -o goose *.go
+```
+
+```
+$ ./goose sqlite3 ./foo.db status
+    Applied At                  Migration
+    =======================================
+    Pending                  -- 00001_create_users_table.sql
+    Pending                  -- 00002_rename_root.go
+
+$ ./goose sqlite3 ./foo.db up
+OK    00001_create_users_table.sql
+OK    00002_rename_root.go
+goose: no migrations to run. current version: 2
+
+$
+    Applied At                  Migration
+    =======================================
+    Mon Jun 19 21:56:00 2017 -- 00001_create_users_table.sql
+    Mon Jun 19 21:56:00 2017 -- 00002_rename_root.go
+```
+
+## Best practice: Split migrations into a standalone package
+
+1. Move [main.go](main.go) into your `cmd/` directory
+
+2. Rename migration functions to `migrations` pkg
+
+3. Import `migrations` package from [cmd/main.go](main.go)
+
+    ```go
+    import (
+        _ "github.com/pressly/goose/example/migrations-go"
+    )
+    ```
+
+    This will cause all `init()` functions to be called within `migrations` pkg, thus registering the migration functions properly.
diff --git a/example/migrations/README.md b/example/migrations/README.md
new file mode 100644
index 0000000..245c3a2
--- /dev/null
+++ b/example/migrations/README.md
@@ -0,0 +1,26 @@
+# SQL migrations only
+
+See [second example](../migrations-go) for Go migrations.
+
+```bash
+$ go get -u github.com/pressly/goose/cmd/goose
+```
+
+```bash
+$ goose sqlite3 ./foo.db status
+    Applied At                  Migration
+    =======================================
+    Pending                  -- 00001_create_users_table.sql
+    Pending                  -- 00002_rename_root.sql
+
+$ goose sqlite3 ./foo.db up
+OK    00001_create_users_table.sql
+OK    00002_rename_root.sql
+goose: no migrations to run. current version: 2
+
+$
+    Applied At                  Migration
+    =======================================
+    Mon Jun 19 21:56:00 2017 -- 00001_create_users_table.sql
+    Mon Jun 19 21:56:00 2017 -- 00002_rename_root.sql
+```