Skip to content

Moving GitLab databases to a different PostgreSQL instance

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Sometimes it is necessary to move your databases from one PostgreSQL instance to another. For example, if you are using AWS Aurora and are preparing to enable Database Load Balancing, you need to move your databases to RDS for PostgreSQL.

To move databases from one instance to another:

  1. Gather the source and destination PostgreSQL endpoint information:

    SRC_PGHOST=<source postgresql host>
    SRC_PGUSER=<source postgresql user>
    DST_PGHOST=<destination postgresql host>
    DST_PGUSER=<destination postgresql user>
  2. Stop GitLab:

    sudo gitlab-ctl stop
  3. Dump the databases from the source:

    /opt/gitlab/embedded/bin/pg_dump -h $SRC_PGHOST -U $SRC_PGUSER -c -C -f gitlabhq_production.sql gitlabhq_production
    /opt/gitlab/embedded/bin/pg_dump -h $SRC_PGHOST -U $SRC_PGUSER -c -C -f praefect_production.sql praefect_production
  4. Restore the databases to the destination (this overwrites any existing databases with the same names):

    /opt/gitlab/embedded/bin/psql -h $DST_PGHOST -U $DST_PGUSER -f praefect_production.sql postgres
    /opt/gitlab/embedded/bin/psql -h $DST_PGHOST -U $DST_PGUSER -f gitlabhq_production.sql postgres
  5. Optional. If you migrate from a database that doesn't use PgBouncer to a database that does, you must manually add a pg_shadow_lookup function to the application database (usually gitlabhq_production).

  6. Configure the GitLab application servers with the appropriate connection details for your destination PostgreSQL instance in your /etc/gitlab/gitlab.rb file:

    gitlab_rails['db_host'] = '<destination postgresql host>'

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

  7. Reconfigure for the changes to take effect:

    sudo gitlab-ctl reconfigure
  8. Restart GitLab:

    sudo gitlab-ctl start