During installation, upgrade or startup, Confluence performs a number of checks. The Database Connection check verifies that Confluence can connect to a database.

Cause

This check may fail because:

• You don't have a database running
• The configuration in your confluence.cfg.xml is incorrect
• Username/Password for your database are incorrect
• If Database password has got changed.
• Your database user doesn't have the correct permissions to connect to the database
• The database specified is not the Confluence database
• You're trying to use an incorrect port
• General network issues that prevent Confluence from connecting to your database, such as:
  • PostgreSQL / MySQL localhost errors
  • Firewall errors
  • Network connection not available/offline

Impact

The Confluence instance needs a database in order to run. Without a database it can't read or write any data for your instance.

Resolution

There's a number of reasons this could be happening. Here's a few things to check. 

Network issue

Lets see if your network is up. Check if your database is reachable by your Confluence instance.

Ping your database server

Can you ping your Database server? Take the URL for your database that's in your confluence.cfg.xml and ping your database.

ping 123.456.789.012

Check your database is running

If you can't ping the database, it may not be running. Make sure your database server is running on the specified address, and accessible. Follow the information for your specific database to achieve this.

Check ports needed for the database connection

If your database is running, next check that the PORT your database tries to connect to is available.

nmap 123.456.789.012

Is the port you need open? It should probably look something like this (in this example we've used PostgreSQL):

❯ nmap 123.456.789.012
Starting Nmap 7.40 ( https://nmap.org ) at 1970-01-01 0:00 AEDT
Nmap scan report for 123.456.789.012
Host is up (0.00083s latency).
Not shown: 498 closed ports, 498 filtered ports
PORT STATE SERVICE
5432/tcp open postgresql
Nmap done: 1 IP address (1 host up) scanned in 13.27 seconds

Check your database and database settings for external connections

If there's no problem with your port, then two things may be happening:

1. The host you point to might be running  - ping was successful - but there is no database running, or
2. Your database only allows connections from localhost. This is the default setting for several database servers such as PostgreSQL or MySQL. Check the information for your specific database on how to setup your database to allow external connections.

Does your user have the correct permissions?

In order to read from and write to the database, the user specified in your confluence.cfg.xml file needs to have the right permissions. 
Check your database to see if the user in your confluence.cfg.xml has the correct permissions.

In PostgreSQL you can run the following command:

psql -U <user> -d <database> -h <host> -p <port> -c "select * from information_schema.role_table_grants where grantee='<user>';"

Replace <user>, <database>, <host>, <port>, and <user> with the appropriate values. 

If you see quite a lot of lines of output, everything should be fine. If you see a fatal error this may be a hint that the permissions are wrong.

Some example errors in PostgreSQL (values in <value> would be your input):

- missing user: psql: FATAL: role "<user>" does not exist
- missing database: psql: FATAL: database "<database>" does not exist

Set up a correct user and/or database

The fix here is different for each database type. Follow the instructions for your specific database on how to setup your database user with the correct permissions.

Check the correct PORT

Every database runs on a certain default port (Postgres has a default port of 5432 for example).
Make sure the port specified in your confluence.cfg.xml is correct.

Try to connect to your database via command line. If you see an error like this in Postgres:

psql: could not connect to server: Connection refused
Is the server running on host "<host>" and accepting
TCP/IP connections on port <port>?

Check the ports

If that is the case, you probably want to check which port is actually opened for your database, if at all. (See networking checks above).
To find out if the database is exposed on a certain port at all try the nmap check as described above as well.