NAV Navbar
Switch version:

Enabling GoCD to use Postgres

This section describes how to bring up a GoCD Server instance, using Postgres as the data store with no existing data. In case you’re looking to migrate the data from an existing GoCD Server instance, take a look at this. Once the data is migrated, you can start configuring the GoCD Server to use the database, by starting from Step 2 below.

Step 1: Initialize Postgres with an empty database

In order to use this add-on, a Postgres server is needed, to host the GoCD Server’s database. Currently, Postgres versions 9.2 to 9.5 are supported by GoCD, older verions are not supported. If the Postgres server is not yet initialized, it needs to be, before GoCD is able to use it. Along with PostgreSQL server, you need to install postgresql-client and postgresql-contrib packages. The postgresql-contrib package contains the citext and pgcrypto module which is necessary for the initial schema creation.

Once initialized and the Postgres service is started, the empty database can be created from the command-line using the psql utility, which Postgres ships with:

$ psql -U postgres -h localhost -c "CREATE DATABASE cruise-or-desired-database-name;"

The GoCD Server uses cruise as the default database name. The database name chosen can be that, or any other valid Postgres database name. While configuring the GoCD Server in a later step, the chosen name can be configured. There is no need to create any schema in that database, since the GoCD Server does it automatically.

Step 2: Install add-on into addons directory

A directory called addons needs to be created (if not already present) in the GoCD Server installation directory. The add-on JAR needs to be placed in that directory. In the examples below, the add-on JAR name is considered to be “go-postgresql-1.2.3.jar”. The name of the real add-on JAR will be different. The commands are:

On Linux (remember to run this as the go user):

$ mkdir -p /var/lib/go-server/addons
$ cp go-postgresql-1.2.3.jar /var/lib/go-server/addons

On Windows:

C:\> md "C:\Program Files (x86)\Go Server\addons"
C:\> copy go-postgresql-1.2.3.jar "C:\Program Files (x86)\Go Server\addons"

The location of GoCD’s installation directory varies per operating system. The documentation provides information about the locations. Usually, on a Linux system using the RPM or Debian installers, this file will need to be at /etc/go/

Step 3: Configure GoCD with Postgres connection details

A Java properties file with the name ‘’ needs to be created in GoCD’s configuration directory. This file should contain information about the Postgres server, so that the GoCD Server can connect to it. Information about the format of this file and valid keys in it can be found in the section Add-on configuration reference.

The location of GoCD’s configuration directory varies per operating system. The documentation provides information about the locations.

Step 4: Configure the database provider for GoCD

At this point, GoCD needs to be configured to use Postgres as its data store rather than the default. This is done by setting the Java system property go.database.provider to com.thoughtworks.go.postgresql.PostgresqlDatabase.

On Linux, this can usually be done by (on a single line):

$ echo 'GO_SERVER_SYSTEM_PROPERTIES="$GO_SERVER_SYSTEM_PROPERTIES -Dgo.database.provider=com.thoughtworks.go.postgresql.PostgresqlDatabase"' >> /etc/default/go-server

On Windows, this can usually be done by adding a line in the appropriate properties file:"-Dgo.database.provider=com.thoughtworks.go.postgresql.PostgresqlDatabase"

The process of setting a system property is detailed here in the documentation.

Step 5: Start the GoCD Server and verify that Postgres is being used

The GoCD Server can now be started.

On Linux:

$ sudo /etc/init.d/go-server start

On Windows:

C:\> net start "Go Server"

You can verify that GoCD is running with Postgres by verifying the below line in the go-server.log, upon starting the service.

[DB] Using connection configuration jdbc:postgresql://[host]:[port]/[database-name] [User: postgres] [Password Encrypted: false]