• Known issues
• Set up multiple databases
  • Installations from source
  • Omnibus GitLab installations
• Further information

Multiple Databases

By default, GitLab uses a single application database, referred to as the main database.

To scale GitLab, you can configure GitLab to use multiple application databases.

Due to known issues, configuring GitLab with multiple databases is in Alpha.

Known issues

• Migrating data from the main database to the ci database is not supported or documented yet.
• Once data is migrated to the ci database, you cannot migrate it back.

Set up multiple databases

Use the following content to set up multiple databases with a new GitLab installation.

There is no documentation for existing GitLab installations yet.

After you have set up multiple databases, GitLab uses a second application database for CI/CD features, referred to as the ci database. For example, GitLab reads and writes to the ci_pipelines table in the ci database.

Installations from source

1. Back up GitLab in case of unforeseen issues.

2. Stop GitLab:

   sudo service gitlab stop
   

3. Open config/database.yml, and add a ci: section under production:. See config/database.yml.decomposed-postgresql for possible values for this new ci: section. Once modified, the config/database.yml should look like:

   production:
     main:
       # ...
     ci:
       adapter: postgresql
       encoding: unicode
       database: gitlabhq_production_ci
       # ...
   

4. Save the config/database.yml file.

5. Update the service files to set the GITLAB_ALLOW_SEPARATE_CI_DATABASE environment variable to true.

6. Create the gitlabhq_production_ci database:

   sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
   sudo -u git -H bundle exec rake db:schema:load:ci
   

7. Lock writes for ci tables in main database, and the other way around:

   sudo -u git -H bundle exec rake gitlab:db:lock_writes
   

8. Restart GitLab:

   sudo service gitlab restart
   

Omnibus GitLab installations

1. Back up GitLab in case of unforeseen issues.

2. Stop GitLab:

   sudo gitlab-ctl stop
   

3. Edit /etc/gitlab/gitlab.rb and add the following lines:

   gitlab_rails['env'] = { 'GITLAB_ALLOW_SEPARATE_CI_DATABASE' => 'true' }
   gitlab_rails['databases']['ci']['enable'] = true
   gitlab_rails['databases']['ci']['db_database'] = 'gitlabhq_production_ci'
   

4. Save the /etc/gitlab/gitlab.rb file.

5. Reconfigure GitLab:

   sudo gitlab-ctl reconfigure
   

6. Optional. Reconfiguring GitLab should create the gitlabhq_production_ci. If it did not, manually create the gitlabhq_production_ci:

   sudo gitlab-ctl start postgresql
   sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h /var/opt/gitlab/postgresql -d template1 -c "CREATE DATABASE gitlabhq_production_ci OWNER gitlab;"
   sudo gitlab-rake db:schema:load:ci
   

7. Lock writes for ci tables in main database, and the other way around:

   sudo gitlab-ctl start postgresql
   sudo gitlab-rake gitlab:db:lock_writes
   

8. Restart GitLab:

   sudo gitlab-ctl restart
   

Further information

For more information on multiple databases, see issue 6168.

For more information on how multiple databases work in GitLab, see the development guide for multiple databases.

Since 2022-07-02, GitLab.com has been running with two separate databases. For more information, see this blog post.