@@ -7,28 +7,25 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo
...
@@ -7,28 +7,25 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo
# Background migrations
# Background migrations
Background migrations can be used to perform data migrations that would
Background migrations should be used to perform data migrations whenever a
otherwise take a very long time (hours, days, years, etc) to complete. For
migration exceeds [the time limits in our guidelines](database_review.md#timing-guidelines-for-migrations). For example, you can use background
example, you can use background migrations to migrate data so that instead of
migrations to migrate data that's stored in a single JSON column
storing data in a single JSON column the data is stored in a separate table.
to a separate table instead.
If the database cluster is considered to be in an unhealthy state, background
If the database cluster is considered to be in an unhealthy state, background
migrations automatically reschedule themselves for a later point in time.
migrations automatically reschedule themselves for a later point in time.
## When To Use Background Migrations
## When To Use Background Migrations
In the vast majority of cases you will want to use a regular Rails migration
You should use a background migration when you migrate _data_ in tables that have
instead. Background migrations should be used when migrating _data_ in
so many rows that the process would exceed [the time limits in our guidelines](database_review.md#timing-guidelines-for-migrations) if performed using a regular Rails migration.
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
- Background migrations should be used when migrating data in [high-traffic tables](migration_style_guide.md#high-traffic-tables).
- 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
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
largely dependent on the size of the dataset, hence it should be split accordingly
and put into background migrations.
and put into background migrations.
- Background migrations should not be used to perform schema migrations.
Background migrations _may not_ be used to perform schema migrations, they
should only be used for data migrations.
Some examples where background migrations can be useful:
Some examples where background migrations can be useful:
