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.3 to 9.6 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.

Steps to install PostgreSQL DB on Linux

# Ubuntu
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo service postgresql start
# CentOS 7 ( for earlier CentOS versions please ensure compatible version of PostgreSQL is installed)
sudo yum update
sudo yum install postgresql-server postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

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

GRANT ALL PRIVILEGES ON DATABASE "cruise" TO "gocd_database_user";
ALTER ROLE "gocd_database_user" SUPERUSER;

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.

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. Usually, on a Linux system using the RPM or Debian installers, this file will need to be at /etc/go/ 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.

Edit the file wrapper-properties.conf on your GoCD server and add the following options. The location of the wrapper-properties.conf can be found in the installation documentation of the GoCD server.

# We recommend that you begin with the index `100` and increment the index for each system property

If you’re running on docker using one of the supported GoCD server images, set the environment variable GOCD_SERVER_JVM_OPTIONS:

docker run -e "GOCD_SERVER_JVM_OPTIONS=-Dgo.database.provider=com.thoughtworks.go.postgresql.PostgresqlDatabase" ...

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

The GoCD Server can now be started.

On Linux:

$ service 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]