diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-14 13:26:13 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-14 13:26:13 +0300 |
commit | 4588bbc93a7857eb2d031a4f3e0212c0aa46b846 (patch) | |
tree | 1c1c9795491b5e6a97a5e8b5f00e4e2dcc99e5a1 /doc/install | |
parent | 8236147d0fcb9f4f8c315f895aebc0c8158e2f7d (diff) |
Add latest changes from gitlab-org/gitlab@13-3-stable-ee
Diffstat (limited to 'doc/install')
-rw-r--r-- | doc/install/postgresql_extensions.md | 76 | ||||
-rw-r--r-- | doc/install/requirements.md | 7 |
2 files changed, 78 insertions, 5 deletions
diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md new file mode 100644 index 00000000000..4156d72097d --- /dev/null +++ b/doc/install/postgresql_extensions.md @@ -0,0 +1,76 @@ +--- +last_updated: 2020-09-01 +--- + +# Managing PostgreSQL extensions + +This guide documents how to manage PostgreSQL extensions for installations with an external +PostgreSQL database. + +GitLab requires certain extensions to be installed into the GitLab database. For example, +GitLab relies on `pg_trgm` and the `btree_gist` extensions. + +In order to install extensions, PostgreSQL requires the user to have superuser privileges. +Typically, the GitLab database user is not a superuser. Therefore, regular database migrations +cannot be used in installing extensions and instead, extensions have to be installed manually +prior to upgrading GitLab to a newer version. + +## Installing PostgreSQL extensions manually + +In order to install a PostgreSQL extension, this procedure should be followed: + +1. Connect to the GitLab PostgreSQL database using a superuser, for example: + + ```shell + sudo gitlab-psql -d gitlabhq_production + ``` + +1. Install the extension (`btree_gist` in this example) using [`CREATE EXTENSION`](https://www.postgresql.org/docs/11/sql-createextension.html): + + ```sql + CREATE EXTENSION IF NOT EXISTS btree_gist + ``` + +1. Verify installed extensions: + + ```shell + gitlabhq_production=# \dx + List of installed extensions + Name | Version | Schema | Description + ------------+---------+------------+------------------------------------------------------------------- + btree_gist | 1.5 | public | support for indexing common datatypes in GiST + pg_trgm | 1.4 | public | text similarity measurement and index searching based on trigrams + plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language + (3 rows) + ``` + +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 + +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 +privileges. + +```shell +== 20200515152649 EnableBtreeGistExtension: migrating ========================= +-- execute("CREATE EXTENSION IF NOT EXISTS btree_gist") + +GitLab requires the PostgreSQL extension 'btree_gist' installed in database 'gitlabhq_production', but +the database user is not allowed to install the extension. + +You can either install the extension manually using a database superuser: + + CREATE EXTENSION IF NOT EXISTS btree_gist + +Or, you can solve this by logging in to the GitLab database (gitlabhq_production) using a superuser and running: + + ALTER regular WITH SUPERUSER + +This query will grant the user superuser permissions, ensuring any database extensions +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. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 4d9f09bb8b0..10d5853c82e 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -140,11 +140,8 @@ GitLab version | Minimum PostgreSQL version 12.10 | 11 13.0 | 11 -You must also ensure the `pg_trgm` and `btree_gist` extensions are loaded into every -GitLab database. These extensions [can be enabled](https://www.postgresql.org/docs/11/sql-createextension.html) using a PostgreSQL super user. - -On some systems you may need to install an additional package (for example, -`postgresql-contrib`) for this extension to become available. +You must also ensure the `pg_trgm` and `btree_gist` extensions are [loaded into every +GitLab database](postgresql_extensions.html). NOTE: **Note:** Support for [PostgreSQL 9.6 and 10 has been removed in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab) so that GitLab can benefit from PostgreSQL 11 improvements, such as partitioning. For the schedule of transitioning to PostgreSQL 12, see [the related epic](https://gitlab.com/groups/gitlab-org/-/epics/2184). |