Commit 4b3d734c authored by Ben Prescott's avatar Ben Prescott Committed by Ben Prescott @bprescott_↙ ☺

PostgreSQL plugin installation requirements

parent 9dc8038c
......@@ -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.
......
......@@ -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
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment