PostgreSQL plugin installation requirements

doc/administration/postgresql/external.md

@@ -19,7 +19,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance:
    [database requirements document](../../install/requirements.md#database).
 1. Set up a `gitlab` user with a password of your choice, create the `gitlabhq_production` database, and make the user an owner of the database. You can see an example of this setup in the [installation from source documentation](../../install/installation.md#6-database).
 1. If you are using a cloud-managed service, you may need to grant additional
-   roles to your `gitlab` user:
+   roles to your `gitlab` user. This is for the installation of plugins during installation
+   and upgrades. As an alternative, [ensure the plugins are installed manually,
+   and read about the problems that may arise during future GitLab upgrades](../../install/postgresql_extensions.md).
    - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role.
    - Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/howto-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role.
 

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.
+In order to recover from failed migrations, the extension needs to be installed manually using 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
+```