Database Setup for PostgreSQL

This page provides instructions for configuring Confluence to use a PostgreSQL database.

Before you start

  • See Supported Platforms to check your version of PostgreSQL is supported. You may need to upgrade your database before installing Confluence.
  • If you're switching from another database, including the embedded evaluation database, read Migrating to Another Database before you begin.

1. Install PostgreSQL

If you don't already have PostgreSQL installed, download and install it now.

A few tips when installing PostgreSQL:

  • The password you provide during the installation process is for the 'postgres' account, which is the database root-level account (the super user). Remember this username and password as you'll need it each time you log in to the database.
  • The default port for PostgreSQL is 5432. If you decide to change the default port, make sure it does not conflict with any other services running on that port. 
  • Choose the locale that best matches your geographic location.
  • Don't launch Stack Builder at the completion of the installer.

2. Create a database user and database

Once you've installed PostgreSQL:

  1. Create a database user, for example confluenceuser
    • Your new user must be able to create database objects and must have can login permission.
       
  2. Next, create a database (for example confluence): 
    • Owner is your new database user (for example confluenceuser)
    • Character encoding must be set to utf8 encoding.
    • Collation must also be set to utf8.  Other collations, such as "C", are known to cause issues with Confluence. 
    • If you are running PostgreSQL on Windows use the equivalent character type and collation for your locale, for example English_United States.1252
    • In Linux systems, if the locale is not utf8, include LC_CTYPE as utf8 during database creation.
    • If you are running PostgreSQL in AWS RDS and have set the collation to en_US.UTF-8, you will see a warning that the collation is incorrect. You can ignore this warning. 

You can use pgAdmin as an alternative to the command line to complete this step.

3. Install Confluence 

Check out the Confluence Installation Guide for step-by-step instructions on how to install Confluence on your operating system. 

4. Enter your database details

The Confluence setup wizard will guide you through the process of connecting Confluence to your database.  Be sure to select "My own database". 

Use a JDBC connection (default)

JDBC is the recommended method for connecting to your database.

The Confluence setup wizard will provide you with two setup options:

  • Simple - this is the most straightforward way to connect to your database.
  • By connection string - use this option if you want to specify additional parameters and are comfortable constructing a database URL. 

Depending on the setup type, you'll be prompted for the following information.

Setup typeFieldDescription
Simple HostnameThis is the hostname or IP address of your database server.  
Simple PortThis is the PostgreSQL port. If you didn't change the port when you installed Postgres, it will default to 5432.
SimpleDatabase name This is the name of your confluence database. In the example above, this is confluence
By connection stringDatabase URLThe database URL is entered in this format:
jdbc:postgresql://<server>:<port>/<database>

For example:  
jdbc:postgresql://localhost:5432/confluence

If you need to connect to an SSL database, add the sslmode=required parameter in the database URL. For example: 
jdbc:postgresql://localhost:5432/confluence?sslmode=required


BothUsernameThis is the username of your dedicated database user. In the example above, this is confluenceuser.
BothPasswordThis is the password for your dedicated database user.

Use a JNDI datasource

If you want to use a JNDI datasource, see Configuring a datasource connection for the steps you'll need to take before you set up Confluence, as the setup wizard will only provide the option to use a datasource if it detects a datasource in your Tomcat configuration. 

5. Test your database connection

In the database setup screen, hit the Test connection button to check:

  • that Confluence can connect to your database server
  • that the database character encoding is correct
  • that your database user has appropriate permissions for the database

Once the test is successful, hit Next to continue with the Confluence setup process. 

If Confluence and PostgreSQL are hosted on different servers, see the PostgreSQL documentation on how to set up pg_hba.conf to make sure Confluence and PostgreSQL can communicate remotely. 

Troubleshooting

  • If Confluence complains that it is missing a class file, you may have placed the JDBC driver in the wrong folder.
  • If you're unable to connect to the database from Confluence and they are on different machines, most likely you have a firewall in between the two machines or your pg_hba.conf file is misconfigured. Verify that your firewall is set to allow connections through 5432 or double check your hba configuration.
  • The following page contains common issues encountered when setting up your PostgreSQL database to work with Confluence: Known issues for PostgreSQL.
  • There's a known collation limitation when running pSQL on Windows (1252 locale is not UTF8). See  CONFSERVER-57749 - Getting issue details... STATUS

Last modified on Nov 6, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.