Use an external PostgreSQL database

You can use an external database instead of the database installed by default on Rudder root servers.

The setup is done in two places: on the database server and on the Rudder root server. It also allows moving an existing database to another server.

On the database side

Rudder requires PostgreSQL 10 or higher.

Create a database (the default name is rudder) on your PostgreSQL server, and create a user with full access to this database.

Make sure to give access to this user from the outside (by editing pg_hba.conf).

Use the same database server for several Rudder root servers

It is possible to share the same database server between several Rudder instances, by following the preceding tip to use a different database than the default one.

On the root server

Initialize the database

The provisioning script is located on the root server in /opt/rudder/share/upgrade-tools/reportsSchema.sql.

If your database has a name different from rudder, you need to make a copy of this file and edit it. Change the line:

ALTER database rudder SET standard_conforming_strings=true;


ALTER database DB_NAME SET standard_conforming_strings=true;

Then initialize the database:

psql -q -U DB_USER -h DB_HOST -d DB_NAME -f reportsSchema.sql

Configure the database

  • Change the hostname in /opt/rudder/etc/, and database name and user if needed:

# Don't try to configure a local postgresql on the root server

# Set connection details

# Don't edit this one, it is managed by the agent
  • Set the database password in /opt/rudder/etc/rudder-passwords.conf, in the RUDDER_PSQL_PASSWORD line.

  • Run the agent on the root server to synchronize the password from rudder-passwords.conf to and restart the rudder-jetty service:

rudder agent run

Your server will now be using the external database.

If the connection fails, the server will not start and you will get more details in the log webapp log file in /var/log/rudder/webapp/${TODAY}.stderrout.log.

Remove PostgreSQL on the root server

If you want to remove PostgreSQL completely from the root server, you need to uninstall the rudder-server-root and rudder-reports packages.

You can then remove the postgresql package and database from the server, but keep in mind you will lose all existing data.

You can follow the backup and restore procedure to migrate the data to the new database.

← Server installation options Integration →