Configure GitLab using an external PostgreSQL service

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed

{{< /details >}}

If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. For example, AWS offers a managed Relational Database Service (RDS) that runs PostgreSQL.

Alternatively, you may opt to manage your own PostgreSQL instance or cluster separate from the Linux package.

If you use a cloud-managed service, or provide your own PostgreSQL instance, set up PostgreSQL according to the database requirements document.

GitLab Rails database

After you set up the external PostgreSQL server:

1. Log in to your database server.

2. 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 self-compiled installation documentation.

3. If you are using a cloud-managed service, you may need to grant additional roles to your gitlab user:

   • Amazon RDS requires the rds_superuser role.
   • Azure Database for PostgreSQL requires the azure_pg_admin role. Azure Database for PostgreSQL - Flexible Server requires allow-listing extensions before they can be installed.
   • Google Cloud SQL requires the cloudsqlsuperuser role.

   This is for the installation of extensions during installation and upgrades. As an alternative, ensure the extensions are installed manually, and read about the problems that may arise during future GitLab upgrades.

4. Configure the GitLab application servers with the appropriate connection details for your external PostgreSQL service in your /etc/gitlab/gitlab.rb file:

   rubyCopy

   # Disable the bundled Omnibus provided PostgreSQL
   postgresql['enable'] = false
   
   # PostgreSQL connection details
   gitlab_rails['db_adapter'] = 'postgresql'
   gitlab_rails['db_encoding'] = 'unicode'
   gitlab_rails['db_host'] = '10.1.0.5' # IP/hostname of database server
   gitlab_rails['db_port'] = 5432
   gitlab_rails['db_password'] = 'DB password'
   

   For more information on GitLab multi-node setups, refer to the reference architectures.

5. Reconfigure for the changes to take effect:

   shellCopy

   sudo gitlab-ctl reconfigure
   

6. Restart PostgreSQL to enable the TCP port:

   shellCopy

   sudo gitlab-ctl restart
   

Container registry metadata database

If you plan to use the container registry metadata database, you should also create the registry database and user.

After you set up the external PostgreSQL server:

1. Log in to your database server.

2. Use the following SQL commands to create the user and the database:

   sqlCopy

   -- Create the registry user
   CREATE USER registry WITH PASSWORD '<your_registry_password>';
   
   -- Create the registry database
   CREATE DATABASE registry OWNER registry;
   

3. For cloud-managed services, grant additional roles as needed:

   {{< tabs >}}

   {{< tab title="Amazon RDS" >}}

   sqlCopy

   GRANT rds_superuser TO registry;
   

   {{< /tab >}}

   {{< tab title="Azure database" >}}

   sqlCopy

   GRANT azure_pg_admin TO registry;
   

   {{< /tab >}}

   {{< tab title="Google Cloud SQL" >}}

   sqlCopy

   GRANT cloudsqlsuperuser TO registry;
   

   {{< /tab >}}

   {{< /tabs >}}

4. You can now enable and start using the container registry metadata database.

Troubleshooting

Resolve SSL SYSCALL error: EOF detected error

When using an external PostgreSQL instance, you may see an error like:

pg_dump: error: Error message from server: SSL SYSCALL error: EOF detected

To resolve this error, ensure that you are meeting the minimum PostgreSQL requirements. After upgrading your RDS instance to a supported version, you should be able to perform a backup without this error. See issue 64763 for more information.