diff --git a/README.md b/README.md index efedf5b..e60d33c 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,7 @@ Goose is a database migration tool. Manage your database schema by creating incr - 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 +- We use timestamped migrations by default but recommend a hybrid approach of using timestamps in the development process and sequential versions in production. # Install @@ -51,7 +49,7 @@ Commands: redo Re-run the latest migration status Dump the migration status for the current DB version Print the current version of the database - create NAME [sql|go] Creates new migration file with next version + create NAME [sql|go] Creates new migration file with the current timestamp Options: -dir string @@ -74,14 +72,14 @@ Examples: Create a new SQL migration. $ goose create add_some_column sql - $ Created new file: 00001_add_some_column.sql + $ Created new file: 20170506082420_add_some_column.sql Edit the newly created file to define the behavior of your migration. You can also create a Go migration, if you then invoke it with [your own goose binary](#go-migrations): $ goose create fetch_user_data go - $ Created new file: 00002_fetch_user_data.go + $ Created new file: 20170506082421_fetch_user_data.go ## up @@ -241,6 +239,11 @@ func Down(tx *sql.Tx) error { } ``` +# Hybrid Versioning +We strongly recommend adopting a hybrid versioning approach, using both timestamps and sequential numbers. Migrations created during the development process are timestamped and sequential versions are ran on production. We believe this method will prevent the problem of conflicting versions when writing software in a team environment. + +To help you adopt this approach, `create` will use the current timestamp as the migration version. When you're ready to deploy your migrations in a production environment, we also provide a helpful `fix` command to convert your migrations into sequential order, while preserving the timestamp ordering. We recommend running `fix` in the CI pipeline, and only when the migrations are ready for production. + ## License Licensed under [MIT License](./LICENSE) diff --git a/cmd/goose/main.go b/cmd/goose/main.go index cfb9043..15b4caf 100644 --- a/cmd/goose/main.go +++ b/cmd/goose/main.go @@ -125,6 +125,7 @@ Commands: reset Roll back all migrations status Dump the migration status for the current DB version Print the current version of the database - create NAME [sql|go] Creates new migration file with next version + create NAME [sql|go] Creates new migration file with the current timestamp + fix Apply sequential ordering to migrations ` ) diff --git a/examples/go-migrations/main.go b/examples/go-migrations/main.go index 1f1ea5a..bb323af 100644 --- a/examples/go-migrations/main.go +++ b/examples/go-migrations/main.go @@ -125,6 +125,7 @@ Commands: redo Re-run the latest migration status Dump the migration status for the current DB version Print the current version of the database - create NAME [sql|go] Creates new migration file with next version + create NAME [sql|go] Creates new migration file with the current timestamp + fix Apply sequential ordering to migrations ` )