info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Check for background migrations before upgrading
Certain releases may require different migrations to be
finished before you update to the newer version.
There are two kinds of migrations:
- [Background migrations](#background-migrations)
- [Batched background migrations](#batched-background-migrations) (available in GitLab 14.0 and later)
Background migrations and batched migrations are not the same, so you should check that both are
complete before updating.
Decrease the time required to complete these migrations by increasing the number of
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51332) in GitLab 13.11, [behind a feature flag](../user/feature_flags.md), disabled by default.
> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12.
There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details.
To update database tables in batches, GitLab can use batched background migrations. These migrations
are created by GitLab developers and run automatically on upgrade. However, such migrations are
limited in scope to help with migrating some `integer` database columns to `bigint`. This is needed to
prevent integer overflow for some tables.
Some installations [may need to run GitLab 14.0 for at least a day](index.md#1400) to complete the database changes introduced by that upgrade.
Batched background migrations are handled by Sidekiq and [run in isolation](../development/database/batched_background_migrations.md#isolation), so an instance can remain operational while the migrations are processed. However, there may be performance degradation on larger instances that are heavily used while batched background migrations are run, so it's a good idea to [actively monitor the Sidekiq status](../user/admin_area/index.md#background-jobs) until all migrations are completed.
### Check the status of batched background migrations
To check the status of batched background migrations:
1. On the top bar, select **Main menu > Admin**.
1. On the left sidebar, select **Monitoring > Background Migrations**.
All migrations must have a `Finished` status before you upgrade GitLab.
The status of batched background migrations can also be queried directly in the database.
1. Log into a `psql` prompt according to the directions for your instance's installation method
(for example, `sudo gitlab-psql` for Omnibus installations).
1. Run the following query in the `psql` session to see details on incomplete batched background migrations:
```sql
select job_class_name, table_name, column_name, job_arguments from batched_background_migrations where status <> 3;
```
If the migrations are not finished and you try to update to a later version,
GitLab prompts you with an error:
```plaintext
Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':
```
If you get this error, [check the batched background migration options](#database-migrations-failing-because-of-batched-background-migration-not-finished) to complete the upgrade.
### Pause batched background migrations in GitLab 14.x
To pause an ongoing batched background migration, use the `disable` command above.
This command causes the migration to complete the current batch, and then wait to start the next batch.
Use the following database queries to see the state of the current batched background migration:
1. Obtain the ID of the running migration:
```sql
SELECT
id,
job_class_name,
table_name,
column_name,
job_arguments
FROM batched_background_migrations
WHERE status <> 3;
```
1. Run this query, replacing `XX` with the ID you obtained in the previous step,
to see the status of the migration:
```sql
SELECT
started_at,
finished_at,
finished_at - started_at AS duration,
min_value,
max_value,
batch_size,
sub_batch_size
FROM batched_background_migration_jobs
WHERE batched_background_migration_id = XX
ORDER BY id DESC
limit 10;
```
1. Run the query multiple times within a few minutes to ensure no new row has been added.
If no new row has been added, the migration has been paused.
1. After confirming the migration has paused, restart the migration (using the `enable`
command above) to proceed with the batch when ready. On larger instances,
background migrations can take as long as 48 hours to complete each batch.
There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details.
To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete.
### Enable or disable automatic batch size optimization
Automatic batch size optimization for batched background migrations is under development but ready for production use.
It is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md)
