Merge branch 'update-background-migrations-docs' into 'master'

Updates background migration docs

See merge request gitlab-org/gitlab!21354

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.
 

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: