diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 0a08360b7279ba061998e8e8cc2f664448861ba1..5e16f83b63ca2bb669347676e70df01a389d89af 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -16,10 +16,15 @@ migrations automatically reschedule themselves for a later point in time. > the migrations. In the vast majority of cases you will want to use a regular Rails migration -instead. Background migrations should _only_ be used when migrating _data_ in +instead. Background migrations should be used when migrating _data_ in tables that have so many rows this process would take hours when performed in a regular Rails migration. +Background migrations _may_ also be used when executing numerous single-row queries +for every item on a large dataset. Typically, for single-record patterns, runtime is +largely dependent on the size of the dataset, hence it should be split accordingly +and put into background migrations. + Background migrations _may not_ be used to perform schema migrations, they should only be used for data migrations. diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 3878589736163a101d84f35bcbec30c3fa42715e..b1c3ed4797686d6117d204ec31b9cb65c8ee5a7a 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -103,10 +103,13 @@ and details for a database reviewer: need to fit comfortably within `15s` - preferably much less than that - on GitLab.com. - For column removals, make sure the column has been [ignored in a previous release](what_requires_downtime.md#dropping-columns) - Check [background migrations](background_migrations.md): - - Establish a time estimate for execution on GitLab.com. - - They should only be used when migrating data in larger tables. - - If a single `update` is below than `1s` the query can be placed + - Establish a time estimate for execution on GitLab.com. For historical purposes, + it's highly recommended to include this estimation on the merge request description. + - If a single `update` is below than `1s` the query can be placed directly in a regular migration (inside `db/migrate`). + - Background migrations are normally used, but not limited to: + - Migrating data in larger tables. + - Making numerous SQL queries per record in a dataset. - Review queries (for example, make sure batch sizes are fine) - Because execution time can be longer than for a regular migration, it's suggested to treat background migrations as post migrations: