If the migrations are not finished and you try to update to a later version,
GitLab prompts you with an error:
You can also run:
```shell
```plaintext
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':
```
```
**For installations from source**
If you get this error, [check the batched background migration options](../user/admin_area/monitoring/background_migrations.md#database-migrations-failing-because-of-batched-background-migration-not-finished) to complete the upgrade.
See [troubleshooting batched background migrations](../user/admin_area/monitoring/background_migrations.md#troubleshooting).
## Dealing with running CI/CD pipelines and jobs
## Dealing with running CI/CD pipelines and jobs
If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries or eventually terminates job handling.
If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries or eventually terminates job handling.
...
@@ -197,7 +222,7 @@ Find where your version sits in the upgrade path below, and upgrade GitLab
...
@@ -197,7 +222,7 @@ Find where your version sits in the upgrade path below, and upgrade GitLab
The following table, while not exhaustive, shows some examples of the supported
The following table, while not exhaustive, shows some examples of the supported
upgrade paths.
upgrade paths.
...
@@ -320,9 +345,11 @@ Git 2.33.x and later is required. We recommend you use the
...
@@ -320,9 +345,11 @@ Git 2.33.x and later is required. We recommend you use the
### 14.3.0
### 14.3.0
-[Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later](#upgrading-to-later-14y-releases).
- Ensure [batched background migrations finish](#batched-background-migrations) before upgrading
to 14.3.Z from earlier GitLab 14 releases.
- Ruby 2.7.4 is required. Refer to [the Ruby installation instructions](../install/installation.md#2-ruby)
- Ruby 2.7.4 is required. Refer to [the Ruby installation instructions](../install/installation.md#2-ruby)
for how to proceed.
for how to proceed.
- GitLab 14.3.0 contains post-deployment migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below:
- GitLab 14.3.0 contains post-deployment migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below:
- Ensure [batched background migrations finish](#batched-background-migrations) before upgrading
for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106)
to 14.2.Z from earlier GitLab 14 releases.
and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.5, you need
to update to at least 14.1.0 that contains the same fix before you update to 14.2.
- GitLab 14.2.0 contains background migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below:
- GitLab 14.2.0 contains background migrations to [address Primary Key overflow risk for tables with an integer PK](https://gitlab.com/groups/gitlab-org/-/epics/4785) for the tables listed below:
for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106)
- It is not required for instances already running 14.0.5 (or higher) to stop at 14.1.Z.
and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.5, you need
14.1 is included on the upgrade path for the broadest compatibility
to update to at least 14.1.0 that contains the same fix before you update to
with self-managed installations, and ensure 14.0.0-14.0.4 installations do not
a later version.
encounter issues with [batched background migrations](#batched-background-migrations).
After you update to 14.1.0,
[batched background migrations need to finish](../user/admin_area/monitoring/background_migrations.md#check-the-status-of-background-migrations)
before you update to a later version.
If the migrations are not finished and you try to update to a later version,
you'll see an error like:
```plaintext
Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':
```
See how to [resolve this error](../user/admin_area/monitoring/background_migrations.md#database-migrations-failing-because-of-batched-background-migration-not-finished).
### 14.0.0
### 14.0.0
- Database changes made by the upgrade to GitLab 14.0 can take hours or days to complete on larger GitLab instances.
These [batched background migrations](#batched-background-migrations) update whole database tables to mitigate primary key overflow and must be finished before upgrading to GitLab 14.2 or higher.
- Due to an issue where `BatchedBackgroundMigrationWorkers` were
- Due to an issue where `BatchedBackgroundMigrationWorkers` were
for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106)
for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106)
that requires an update to at least 14.0.5.
that requires an update to at least 14.0.5. The fix was also released in [14.1.0](#1410).
After you update to 14.0.5 or a later 14.0 patch version,
After you update to 14.0.5 or a later 14.0 patch version,
[batched background migrations need to finish](../user/admin_area/monitoring/background_migrations.md#check-the-status-of-background-migrations)
[batched background migrations need to finish](#batched-background-migrations)
before you update to a later version.
before you update to a later version.
If the migrations are not finished and you try to update to a later version,
If the migrations are not finished and you try to update to a later version,
...
@@ -419,6 +432,16 @@ See how to [resolve this error](../user/admin_area/monitoring/background_migrati
...
@@ -419,6 +432,16 @@ See how to [resolve this error](../user/admin_area/monitoring/background_migrati
You should instead follow a [supported upgrade path](#upgrade-paths).
You should instead follow a [supported upgrade path](#upgrade-paths).
- The support of PostgreSQL 11 [has been dropped](../install/requirements.md#database). Make sure to [update your database](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server) to version 12 before updating to GitLab 14.0.
- The support of PostgreSQL 11 [has been dropped](../install/requirements.md#database). Make sure to [update your database](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server) to version 12 before updating to GitLab 14.0.
#### Upgrading to later 14.Y releases
- Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later,
because of [batched background migrations](#batched-background-migrations).
1. Upgrade first to either:
- 14.0.5 or a later 14.0.Z patch release.
- 14.1.0 or a later 14.1.Z patch release.
1.[Batched background migrations need to finish](#batched-background-migrations)
before you update to a later version [and may take longer than usual](#1400).
### 13.11.0
### 13.11.0
Git 2.31.x and later is required. We recommend you use the
Git 2.31.x and later is required. We recommend you use the
