diff options
Diffstat (limited to 'doc/development/background_migrations.md')
| -rw-r--r-- | doc/development/background_migrations.md | 17 |
1 files changed, 11 insertions, 6 deletions
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 0a08360b727..8a1db615022 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -10,16 +10,16 @@ migrations automatically reschedule themselves for a later point in time. ## When To Use Background Migrations -> **Note:** -> When adding background migrations _you must_ make sure they are announced in the -> monthly release post along with an estimate of how long it will take to complete -> 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. @@ -29,6 +29,11 @@ Some examples where background migrations can be useful: - Populating one column based on JSON stored in another column. - Migrating data that depends on the output of external services (e.g. an API). +> **Note:** +> If the background migration is part of an important upgrade, make sure it's announced +> in the release post. Discuss with your Project Manager if you're not sure the migration falls +> into this category. + ## Isolation Background migrations must be isolated and can not use application code (e.g. |