NAV Navbar
Switch version:

Migrating an existing GoCD Server installation to Postgres

Step 1: Upgrade, backup and stop the GoCD Server

Step 1.1: Upgrade the GoCD Server to the latest version.

Step 1.2: Then, backup the H2 database and configuration using the One Click Backup feature of GoCD. During the migration process from H2 to Postgres, data from the backed-up H2 database will be exported into CSV files and no modifications will be done on the H2 database.

Step 1.3: Stop the GoCD Server and ensure that the cruise.lock.db file does not exist under the db/h2db directory, indicating a clean shutdown has finished.

Step 2: Get everything ready for migration

2.1 Create a new directory for migration. In this document, the chosen directory will be /tmp/migration and it will be referred to as the “migration location” for the rest of this document.

2.2 Place the PostgreSQL add-on for GoCD into the migration location. Copy cruise.h2.db (from the backup or from /var/lib/go-server/db/h2db) to the migration location.

2.3 Create a directory called “config” in the migration location (if the migration location is /tmp/migration, the config directory should be /tmp/migration/config). In that directory, place all the configuration files needed to tell GoCD about the Postgres instance it needs to use. At a minimum, this needs to contain a file called “”. More information about the format of these files and valid keys in them can be found in the section “Add-on configuration reference”.

2.4 Create an empty database on the Postgres instance. This needs to have the same name as the key in the file from Step 2.3. Here is an example:

$ psql -U postgres -h localhost -c 'CREATE DATABASE cruise-or-desired-database-name ENCODING="UTF8" TEMPLATE="template0";'

Step 3: Run the migration!

At this point, the migration directory should look like the one below:

|-- tmp/
   |-- migration/
      |-- config/
         |-- cipher [optional: depends on whether db.passwordEncrypted is set to true]
         |-- client.crt ... [optional: depends on Postgres SSL setup]
      |-- cruise.h2.db
      |-- go-postgresql-1.2.3.jar

The migration can now be run from the command-line, in the migration directory:

$ cd /tmp/migration
$ java -Dcruise.config.dir=/tmp/migration/config -Dgo.h2.db.location=/tmp/migration -jar go-postgresql-1.2.3.jar

On Windows, the arguments to the command will be the same. The locations will need to be Windows-specific (like C:\tmp\migration).

Step 4: Use GoCD with the newly migrated database

After a successful migration, the steps mentioned in Enabling GoCD to use Postgres section can now be followed to setup GoCD to use Postgres. “Step 1: Initialize Postgres with an empty database” can be ignored, since Postgres is already initialized with the migrated data.

Migrating an existing GoCD Server Installation to use PostgreSQL Database on Amazon RDS

During the database migrations process, since the rds_superuser isn’t a full superuser, it can cause the migrations to fail. To avoid this the users can follow the below mentioned steps

  1. Bring up a local PostgreSQL server. Using a database superuser account, perform the migration on this local PostgreSQL server.

  2. Once the migration is successful, take a database dump of the migrated DB:

pg_dump --no-owner -h <db-host> -p <db-port> -U <db-user> --dbname=<gocd-server-database-name> <db-dump-file-name>.sql
  1. Create a PostgreSQL database on RDS and make the superuser (who is part of rds_superuser group), the owner of that database.

  2. Using the <db-dump-file-name>.sql created in step 2 above, restore the PostgreSQL database on your Amazon RDS instance

psql -f <db-dump-file-name>.sql -h <rds-db-endpoint> -p <rds-pg-db-port> -U <rds-pg-db-user> --password --dbname=<rds-pg-db-name>`

The above command will prompt for <rds-pg-db-user-password>.

Once the database is restored you can point your GoCD server to that Amazon RDS instance.

Please contact support for any queries or issues.