A root certificate bundle that validates the server's certificate
(root.crt). By default, Omnibus GitLab will use the embedded certificate
bundle in /opt/gitlab/embedded/ssl/certs/cacert.pem. This is not required for
self-signed certificates

A self-signed certificate and private key will be automatically generated for
use. If you'd prefer to use a CA-signed certificate, follow the steps below.

Note that the location of these files can be configurable, but the private key
MUST be readable by the gitlab-psql user. Omnibus will automatically manage
the permissions of the files for you, but you must ensure that the
gitlab-psql can access the directory the files are placed in, if the paths
are customized.

Note that server.crt and server.key may be different from the default SSL
certificates used to access GitLab. For example, suppose the external hostname
of your database is database.example.com, and your external GitLab hostname
is gitlab.example.com. You will either need a wildcard certificate for
*.example.com or two different SSL certificates.

Reconfigure GitLab for the changes to take effect. This will result in a database restart.

Using a non-packaged PostgreSQL database management server

By default, GitLab is configured to use the PostgreSQL server that is included
in Omnibus GitLab. You can also reconfigure it to use an external instance of
PostgreSQL.

WARNING If you are using non-packaged PostgreSQL server, you need to make
sure that PostgreSQL is set up according to the database requirements document.

Edit /etc/gitlab/gitlab.rb:

# Disable the built-in Postgrespostgresql['enable']=false# Fill in the connection details for database.ymlgitlab_rails['db_adapter']='postgresql'gitlab_rails['db_encoding']='utf8'gitlab_rails['db_host']='127.0.0.1'gitlab_rails['db_port']=5432gitlab_rails['db_username']='USERNAME'gitlab_rails['db_password']='PASSWORD'

Don't forget to remove the # comment characters at the beginning of these
lines.

Note:

/etc/gitlab/gitlab.rb should have file permissions 0600 because it contains
plain-text passwords.

Backup and restore a non-packaged PostgreSQL database

When using the rake backup create and restore task, GitLab will
attempt to use the packaged pg_dump command to create a database backup file
and the packaged psql command to restore a backup. This will only work if
they are the correct versions. Check the versions of the packaged pg_dump and
psql:

If these versions are different from your non-packaged external PostgreSQL
(most likely they are different), you need to add symbolic links to your
non-packaged PostgreSQL:

Check the location of the non-packaged executables:

which pg_dump psql

This will output something like:

/usr/bin/pg_dump
/usr/bin/psql

Add symbolic links to the non-packaged versions:

ln -s /usr/bin/pg_dump /usr/bin/psql /opt/gitlab/bin/

Check the versions:

/opt/gitlab/bin/pg_dump --version
/opt/gitlab/bin/psql --version

They should now be the same as your non-packaged external PostgreSQL.

After this is done, ensure that the backup and restore tasks are using the
correct executables by running both the backup and
restore tasks.

Configure packaged PostreSQL server to listen on TCP/IP

The packaged PostgreSQL server can be configured to listen for TCP/IP connections,
with the caveat that some non-critical scripts expect UNIX sockets and may misbehave.

In order to configure the use of TCP/IP for the database service, changes will
need to be made to both postgresql and gitlab_rails sections of gitlab.rb.

Configure postgresql block

The following settings are affected in the postgresql block:

listen_address controls the address on which PostgreSQL will listen.

port controls the port on which PostgreSQL will listen, and must be set if listen_address is.

md5_auth_cidr_adresses is a list of CIDR address blocks which are allowed to
connect to the server, after authentication via password.

trust_auth_cidr_addresses is a list of CIDR address blocks which are allowed
to connect to the server, without authentication of any kind. Be very careful
with this setting. It is suggest that this be limited to the loopback address of
127.0.0.1/24 or even 127.0.0.1/32.

sql_user costrols the expected username for MD5 authentication. This defaults
to gitlab, and is not a required setting.

sql_user_password csets the password that PostgrSQL will accept for MD5
authentication. Replace securesqlpassword in the example below with an acceptable
password.

Any client or GitLab service which will connect over the network will need to
provide the values of sql_user for the username, and password provided to the
configuration when connecting to the PostgreSQL server. They must also be within the network block provided to md5_auth_cidr_addresses

Configure gitlab-rails block

To configure the gitlab-rails application to connect to the PostgreSQL database
over the network, several settings must be confgured.

db_host needs to be set to the IP address of the database sever. If this is
on the same instance as the PostgrSQL service, this can be 127.0.0.1 and will
not require password authentication.

db_port sets the port on the PostgreSQL server to connect to, and must be set
if db_host is set.

db_username configures the username with which to connect to PostgreSQL. This
defaults to gitlab.

db_password must be provided if connecting to PostgreSQL over TCP/IP, and from
an instance in the postgresql['md5_auth_cidr_addresses'] block from settings
above. This is not required if you are connecting to 127.0.0.1 and have configured
postgresql['trust_auth_cidr_addresses'] to include it.

Apply and restart services

After making the changes above, an administrator should run gitlab-ctl reconfigure.
If you experience any issues in regards to the service not listening on TCP, try
directly restarting the service with gitlab-ctl restart postgresql

Note:
Some included scripts of the Omnibus package, such as gitlab-psql expect the
connections to Postgres to be handled over the UNIX socket, and may not function
properly. You can enable TCP/IP without disabling UNIX sockets.

Using a MySQL database management server (Enterprise Edition only)

Note:
Using MySQL with the Omnibus GitLab package is considered deprecated. Although
GitLab Enterprise Edition will still work when MySQL is used, there will be some
limitations as outlined in the database requirements document.

MySQL in Omnibus GitLab package is only supported in GitLab Enterprise Edition
Starter and Premium. The MySQL server itself is not shipped with Omnibus, you
will have to install it on your own or use an existing one. Omnibus ships only
the MySQL client.

The following guide assumes that you want to use MySQL or MariaDB and are using
the GitLab Enterprise Edition packages.

Important note:
If you are connecting Omnibus GitLab to an existing GitLab database you should
create a backup before attempting this procedure.

First, set up your database server according to the upstream GitLab
instructions. If you want to keep using an existing GitLab
database you can skip this step.

Next, add the following settings to /etc/gitlab/gitlab.rb:

# Disable the built-in Postgrespostgresql['enable']=false# Fill in the values for database.ymlgitlab_rails['db_adapter']='mysql2'gitlab_rails['db_encoding']='utf8'gitlab_rails['db_host']='127.0.0.1'gitlab_rails['db_port']=3306gitlab_rails['db_username']='USERNAME'gitlab_rails['db_password']='PASSWORD'

db_adapter and db_encoding should be like the example above. Change
all other settings according to your MySQL setup.

Note:/etc/gitlab/gitlab.rb should have file permissions 0600 because it contains
plain-text passwords.

Seed the database (fresh installs only)

Omnibus GitLab will not automatically seed your external database. Run the
following command to import the schema and create the first admin user:

# Remove 'sudo' if you are the 'git' usersudo gitlab-rake gitlab:setup

If you want to specify a password for the default root user, specify the
initial_root_password setting in /etc/gitlab/gitlab.rb before running the
gitlab:setup command above:

gitlab_rails['initial_root_password']='nonstandardpassword'

If you want to specify the initial registration token for shared GitLab Runners,
specify the initial_shared_runners_registration_token setting in /etc/gitlab/gitlab.rb
before running the gitlab:setup command:

gitlab_rails['initial_shared_runners_registration_token']='token'

Disabling automatic database migration

If you have multiple GitLab servers sharing a database, you will want to limit the
number of nodes that are performing the migration steps during reconfiguration.

Don't forget to remove the # comment characters at the beginning of this
line.

Note:/etc/gitlab/gitlab.rb should have file permissions 0600 because it contains
plain-text passwords.

The next time a reconfigure is triggered, the migration steps will not be performed.

Upgrade packaged PostgreSQL server

As of GitLab 10.0, PostgreSQL 9.6.X is the only database version in GitLab.

If you're still running on the bundled PostgreSQL 9.2.18 when you upgrade to GitLab 10.0,
it will fail and remain on your current version.
To ensure you're running the latest version of the bundled PostgreSQL, first upgrade GitLab to the latest 9.5.X release.

If you had previously avoided the upgrade by touching /etc/gitlab/skip-auto-migrations this will no longer work.

If you want to manually upgrade without upgrading GitLab, you can follow these instructions:

You will need to have sufficient disk space for two copies of your database. Do not attempt to upgrade unless you have enough free space available. Check your database size using sudo du -sh /var/opt/gitlab/postgresql/data (or update to your database path) and space available using sudo df -h. If the partition where the database resides does not have enough space, you can pass the argument --tmp-dir $DIR to the command.

Please note:

This upgrade requires downtime as the database must be down while the upgrade is being performed.
The length of time depends on the size of your database.
If you would rather avoid downtime, it is possible to upgrade to a new database using Slony.
Please see our guide on how to perform the upgrade.

Once you have confirmed that the the above checklist is satisfied,
you can proceed.
To perform the upgrade, run the command:

sudo gitlab-ctl pg-upgrade

This command performs the following steps:

Checks to ensure the database is in a known good state

Shuts down the existing database, any unnecessary services, and enables the gitlab deploy page.

Changes the symlinks in /opt/gitlab/embedded/bin/ for PostgreSQL to point to the newer version of the database

Creates a new directory containing a new, empty database with a locale matching the existing database

Uses the pg_upgrade tool to copy the data from the old database to the new database

Moves the old database out of the way

Moves the new database to the expected location

Calls sudo gitlab-ctl reconfigure to do the required configuration changes, and start the new database server.

Start the remaining services, and remove the deploy page.

If any errors are detected during this process, it should immediately revert to the old version of the database.

Once this step is complete, verify everything is working as expected.

Once you have verified that your GitLab instance is running correctly,
you can remove the old database with:

sudo rm -rf /var/opt/gitlab/postgresql/data.9.2.18

Upgrading a GitLab HA cluster

If you have setup your GitLab instance per the GitLab HA documentation, upgrade the database server last. It should not be necessary to perform any other extra steps.

You do not need to run pg-upgrade on any node besides the database node, but they should be updated to the latest version of GitLab before the database is updated.

Troubleshooting upgrades in an HA cluster

If at some point, the bundled PostgreSQL had been running on a node before upgrading to an HA setup, the old data directory may remain. This will cause gitlab-ctl reconfigure to downgrade the version of the PostgreSQL utilities it uses on that node. Move (or remove) the directory to prevent this: