diff options
Diffstat (limited to 'doc/development/migration_style_guide.md')
-rw-r--r-- | doc/development/migration_style_guide.md | 34 |
1 files changed, 26 insertions, 8 deletions
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index f59c1fd8368..5764c876e4d 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -52,9 +52,18 @@ work it needs to perform and how long it takes to complete: of release manager through the [post-deploy migration pipeline](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). These migrations can be used for schema changes that aren't critical for the application to operate, or data migrations that take at most a few minutes. Common examples for schema changes that should run post-deploy include: + - Clean-ups, like removing unused columns. - Adding non-critical indices on high-traffic tables. - Adding non-critical indices that take a long time to create. + + These migrations should not be used for schema changes that are critical for the application to operate. Making such + schema changes in a post-deployment migration have caused issues in the past, for example [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/378582). + Changes that should always be a regular schema migration and not be executed in a post-deployment migration include: + + - Creating a new table, example: `create_table`. + - Adding a new column to an existing table, example: `add_column`. + 1. [**Batched background migrations.**](database/batched_background_migrations.md) These aren't regular Rails migrations, but application code that is executed via Sidekiq jobs, although a post-deployment migration is used to schedule them. Use them only for data migrations that exceed the timing guidelines for post-deploy migrations. Batched background migrations should _not_ change the schema. @@ -897,9 +906,14 @@ end Table **has records** but **no foreign keys**: -- First release: Remove the application code related to the table, such as models, -controllers and services. -- Second release: Use the `drop_table` method in your migration. +- Remove the application code related to the table, such as models, + controllers and services. +- In a post-deployment migration, use `drop_table`. + +This can all be in a single migration if you're sure the code is not used. +If you want to reduce risk slightly, consider putting the migrations into a +second merge request after the application changes are merged. This approach +provides an opportunity to roll back. ```ruby def up @@ -913,12 +927,16 @@ end Table **has foreign keys**: -- First release: Remove the application code related to the table, such as models, -controllers, and services. -- Second release: Remove the foreign keys using the `with_lock_retries` -helper method. Use `drop_table` in another migration file. +- Remove the application code related to the table, such as models, + controllers, and services. +- In a post-deployment migration, remove the foreign keys using the + `with_lock_retries` helper method. In another subsequent post-deployment + migration, use `drop_table`. -**Migrations for the second release:** +This can all be in a single migration if you're sure the code is not used. +If you want to reduce risk slightly, consider putting the migrations into a +second merge request after the application changes are merged. This approach +provides an opportunity to roll back. Removing the foreign key on the `projects` table: |