From a90bb0f6230b37aa6b76c39013def2c7c15a8d1d Mon Sep 17 00:00:00 2001 From: Mike Arpaia Date: Tue, 14 Feb 2017 13:16:26 -0700 Subject: [PATCH] Updating the migrations docs (#1218) --- docs/development/README.md | 4 +- docs/development/contributing-code.md | 67 ------------------------- docs/development/database-migrations.md | 39 ++++++++++++++ 3 files changed, 41 insertions(+), 69 deletions(-) delete mode 100644 docs/development/contributing-code.md create mode 100644 docs/development/database-migrations.md diff --git a/docs/development/README.md b/docs/development/README.md index 83bfa1869e..6f1dfe1b91 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -6,7 +6,7 @@ The Kolide application is a Go API server which serves a React/Redux single-page ## Building and contributing code - For documentation on building the Kolide source code, see the [Building The Code](./building-the-code.md) guide. -- To learn about how some development practices work within the Kolide application (such as adding database migrations, populating the application with default seed data, etc), see the [Contributing Code](./contributing-code.md) document. +- To learn about database migrations and populating the application with default seed data, see the [Database Migrations](./database-migrations.md) document. ## Running tests @@ -14,4 +14,4 @@ For information on running the various tests that Kolide application contains (J ## Using development infrastructure and tooling -The Kolide application uses a lot of docker tooling to make setting up a development environment quick and easy. For information on this, see the [Development Infrastructure](./development-infrastructure.md) document. \ No newline at end of file +The Kolide application uses a lot of docker tooling to make setting up a development environment quick and easy. For information on this, see the [Development Infrastructure](./development-infrastructure.md) document. diff --git a/docs/development/contributing-code.md b/docs/development/contributing-code.md deleted file mode 100644 index fd2a4cd407..0000000000 --- a/docs/development/contributing-code.md +++ /dev/null @@ -1,67 +0,0 @@ -Contributing Code -================= - -## Database Modifications - -### Adding/Updating tables - -Database schemas are managed by a series of migrations defined in go code. We use a customized version of the Goose migrations tool to handle these migrations. - -Note: Once committed to the Kolide repo, table migrations should be considered immutable. Any changes to an existing table should take place in a new migration executing ALTERs. - - * From the project root run the following shell commands: - - ``` bash - go get github.com/kolide/goose - cd server/datastore/mysql/migrations/tables - goose create AddColumnFooToUsers - ``` - - * Find the file you created in the migrations directory and edit it - - ``` go - package migration - - import ( - "database/sql" - - "github.com/kolide/goose" - ) - - func init() { - goose.AddMigration(Up_20161118212656, Down_20161118212656) - } - - func Up_20161118212656(tx *sql.Tx) error { - _, err := tx.Exec("ALTER TABLE `users` ADD COLUMN `foo` varchar(10) NOT NULL;") - return err - } - - func Down_20161118212656(tx *sql.Tx) error { - _, err := tx.Exec("ALTER TABLE `users` DROP COLUMN `foo`;") - return err - } - ``` - - * Update the database by running the following shell commands: - - ``` bash - make build - build/kolide prepare db - ``` - -### Populating the database with default data - -Populating built in data is also performed through migrations. All table migrations are performed before any data migrations. - -Note: Data migrations can be mutable. If tables are altered in a way that would render a data migration invalid (columns changed/removed), data migrations should be updated to comply with the new schema. Data migrations will not be re-run when they have already been run against a database, but they must be updated to maintain compatibility with a fresh DB. - - * From the project root run the following shell commands: - - ``` bash - go get github.com/kolide/goose - cd server/datastore/mysql/migrations/data - goose create PopulateFoo - ``` - - * Proceed as for table migrations, editing and running the newly created migration file. diff --git a/docs/development/database-migrations.md b/docs/development/database-migrations.md new file mode 100644 index 0000000000..ae0894dc32 --- /dev/null +++ b/docs/development/database-migrations.md @@ -0,0 +1,39 @@ +Database Migrations +=================== + +## Adding/Updating tables + +Database schemas are managed by a series of migrations defined in go code. We use a customized version of the Goose migrations tool to handle these migrations. + +Note: Once committed to the Kolide repo, table migrations should be considered immutable. Any changes to an existing table should take place in a new migration executing ALTERs. + +From the project root run the following shell commands: + +``` bash +go get github.com/kolide/goose +cd server/datastore/mysql/migrations/tables +goose create AddColumnFooToUsers +``` + +Find the file you created in the migrations directory and edit it. You can then update the database by running the following shell commands: + +``` bash +make build +build/kolide prepare db +``` + +## Populating the database with default data + +Populating built in data is also performed through migrations. All table migrations are performed before any data migrations. + +Note: Data migrations can be mutable. If tables are altered in a way that would render a data migration invalid (columns changed/removed), data migrations should be updated to comply with the new schema. Data migrations will not be re-run when they have already been run against a database, but they must be updated to maintain compatibility with a fresh DB. + +From the project root run the following shell commands: + +``` bash +go get github.com/kolide/goose +cd server/datastore/mysql/migrations/data +goose create PopulateFoo +``` + +Proceed as for table migrations, editing and running the newly created migration file.