diff --git a/docs/Contributing/Migrations.md b/docs/Contributing/Migrations.md index 2523754e9f..f48d3acf4b 100644 --- a/docs/Contributing/Migrations.md +++ b/docs/Contributing/Migrations.md @@ -6,13 +6,13 @@ ## 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. +We manage database schemas 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 Fleet repo, table migrations should be considered immutable. Any changes to an existing table should take place in a new migration executing ALTERs. +Note: Table migrations should be considered immutable once committed to the Fleet repo. Any changes to an existing table should occur in a new migration executing ALTERs. -Also note that we don't use the `Down` part of the migrations anymore (older migrations did implement them). The `Down` function should just `return nil`, as we use forward-only migrations. +Also, note that we don't use the `Down` part of the migrations anymore (older migrations did implement them). The `Down` function should just `return nil`, as we use forward-only migrations. -From the project root run the following shell command: +From the project root, run the following shell command: ``` bash make migration name=NameOfMigration @@ -31,11 +31,11 @@ make fleet Note: This pattern will soon be changing. Please check with @zwass if you think you need to write a data migration. -Populating built in data is also performed through migrations. All table migrations are performed before any data migrations. +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 command: +From the project root, run the following shell command: ``` bash make migration name=NameOfMigration @@ -45,4 +45,4 @@ Move the migration file from [server/datastore/mysql/migrations/tables/](../../s Proceed as for table migrations, editing and running the newly created migration file. - \ No newline at end of file +