Problem

During Installation, Upgrade or Startup, JIRA performs a number of checks. The Database Connection check verifies that JIRA can connect to a Database, as this is vital for JIRA to run.

Cause

The reasons for this check to fail are:

• You don't have a database running
• The configuration in your dbconfig.xml is incorrect
• Username/Password for your database are incorrect
• Your database user doesn't have the correct permissions to connect to the database
• The database specified is not the JIRA database
• You're trying to use an incorrect port
• General network issues that prevent JIRA from connecting to your database include:
  • Postgres/Mysql localhost errors
  • Firewall errors
  • Network connection not available/offline

Impact

The JIRA instance needs a database in order to run. Without a database, it can't read any previously created Issues or store newly created issues.

Resolution

Given that there's a number of reasons this could be happening, there are a few things you may need to check to resolve this.

These steps do not apply when using the embedded H2 database. If you have issues with the embedded H2 database, you can refer to the following article to verify access to it: Access the H2 embedded database. 

Network issue

Check to see if your network is up and check if your database is reachable for your JIRA instance.

Ping your database server

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

ping 123.456.789.012

Fix: 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 that is successful check if 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 for Postgres):

❯ 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

Fix: Check your database and database settings for external connections

If this is not the case 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 Postgres 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 dbconfig.xml file needs to have the right permissions. 
Check your database to see if the user in your dbconfig.xml has the correct permissions.

In Postgres you can run this:
(you need to replace <user>, <database>, <host>, <port>, and <user> with the appropriate values for this query to work)

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

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 Postgres (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

Fix: 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 dbconfig.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>?

Fix: 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.