Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42

1 files changed, 19 insertions, 3 deletions

diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md
index 663ec547733..80bbb0671b9 100644
--- a/doc/install/postgresql_extensions.md
+++ b/doc/install/postgresql_extensions.md
@@ -54,7 +54,19 @@ In order to install a PostgreSQL extension, this procedure should be followed:
 On some systems you may need to install an additional package (for example,
 `postgresql-contrib`) for certain extensions to become available.
 
-## A typical migration failure scenario
+## Typical failure scenarios
+
+The following is an example of a new GitLab installation failing because the extension hasn't been
+installed first.
+
+```shell
+---- Begin output of "bash"  "/tmp/chef-script20210513-52940-d9b1gs" ----
+STDOUT: psql:/opt/gitlab/embedded/service/gitlab-rails/db/structure.sql:9: ERROR:  permission denied to create extension "btree_gist"
+HINT:  Must be superuser to create this extension.
+rake aborted!
+failed to execute:
+psql -v ON_ERROR_STOP=1 -q -X -f /opt/gitlab/embedded/service/gitlab-rails/db/structure.sql --single-transaction gitlabhq_production
+```
 
 The following is an example of a situation when the extension hasn't been installed before running migrations.
 In this scenario, the database migration fails to create the extension `btree_gist` because of insufficient
@@ -79,5 +91,9 @@ This query will grant the user superuser permissions, ensuring any database exte
 can be installed through migrations.
 ```
 
-In order to recover from this situation, the extension needs to be installed manually using a superuser, and
-the database migration (or GitLab upgrade) can be retried afterwards.
+To recover from failed migrations, the extension must be installed manually by a superuser, and the
+GitLab upgrade completed by [re-running the database migrations](../administration/raketasks/maintenance.md#run-incomplete-database-migrations):
+
+```shell
+sudo gitlab-rake db:migrate
+```