Database Connection Settings healthcheck fails in Jira server

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

About the Health Check

This health check reviews the current database connection settings in use. The check reviews the settings to confirm that an optimal configuration is set. An optimal configuration will improve stability and protect against problems relating to Database Connection Pools when using an External Database (Such as MS SQL, MySQL, Oracle or PostgreSQL). Only JDBC Datasource connections are checked. Embedded Databases (Such as H2) and database configurations relying on a JNDI configuration are not checked.

Understanding the Results

Depending on your database you will see different results:


H2/HSQLDB Database (Embedded Database)

JIRA is using the embedded database. Due to this the database configuration check has not been done.

Because JIRA is using an Embedded Database, this check has not been completed.

Using an Embedded database is not supported in a production environment.

Microsoft SQL Server

The database configuration is using our recommended settings.

The database connection configuration settings are healthy.


The database configuration ' <flag-name> ' is not set as per our recommended settings.

There is a misconfiguration in your database connection configuration.

The following database configurations are not set as per our recommended settings: <list-of-flags>

There are multiple misconfigurations in your database connection configuration.

MySQL Server

The database configuration is using our recommended settings.

The database connection configuration settings are healthy.


The database configuration '<flag-name>' is not set as per our recommended settings.

There is a misconfiguration in your database connection configuration.

The following database configurations are not set as per our recommended settings: <list-of-flags>

There are multiple misconfigurations in your database connection configuration.

Oracle Database

The database configuration is using our recommended settings.

The database connection configuration settings are healthy.


The database configuration '<flag-name>' is not set as per our recommended settings.

There is a misconfiguration in your database connection configuration.

The following database configurations are not set as per our recommended settings: <list-of-flags>

There are multiple misconfigurations in your database connection configuration.

PostgreSQL Server

The database configuration is using our recommended settings.

The database connection configuration settings are healthy.


The database configuration '<flag-name>' is not set as per our recommended settings.

There is a misconfiguration in your database connection configuration.

The following database configurations are not set as per our recommended settings: <list-of-flags>

There are multiple misconfigurations in your database connection configuration.

Unknown Database Configuration (JNDI)

The database connection is not configured using dbconfig.xml. Due to this the database configuration check has not been done.

The database connection is using a JNDI Connection, and not the dbconfig.xml file. This check will only validate non-JNDI connections.


Impact

In most cases, a configuration that does cause the Health Check to report a warning will likely result in a potential database communication error in the future or slower interaction with the database. A database communication problem may result in JIRA becoming unavailable to users, while slow communications might result in timeouts being experienced within JIRA. Ideally the documented database configuration should be used. Very limited situations may still warrant an alternative configuration to the one prescribed. 

Why is this not set by default for new installs?

It is, as of JIRA 7.1.4 and higher. Previous versions of JIRA that execute this health check will experience warnings with the default configuration - any future installs that are configured as a new install will not. If upgrading to 7.1.4 from a previous version, the dbconfig.xml is not updated automatically so will need to be done manually.

Resolution

H2/HSQLDB Database (Embedded Database)

Using an Embedded database is not supported in a production environment. If you are using an Embedded database with JIRA in a production environment, please follow the steps in: Switching Databases to achieve this.

Microsoft SQL Server

To resolve issues with the database connection update the dbconfig.xml file with the configuration and restart your JIRA instance.

  1. Locate the dbconfig.xml file ls located under: JIRA_HOME/dbconfig.xml.
  2. Update the dbconfig.xml file to ensure it matches the recommendations in the documentation.
    • An example dbconfig.xml file that contains all required arguments has been provided below:

      <jira-database-config>
      <name>defaultDS</name>
      <delegator-name>default</delegator-name>
      <database-type>mssql</database-type>
      <schema-name>jiraschema</schema-name>
      <jdbc-datasource>
        <url>jdbc:jtds:sqlserver://dbserver:1433/jiradb</url>
        <driver-class>net.sourceforge.jtds.jdbc.Driver</driver-class>
        <username>jiradbuser</username>
        <password>password</password>
        <pool-min-size>20</pool-min-size>
        <pool-max-size>20</pool-max-size>
        <pool-max-wait>30000</pool-max-wait>
        <pool-max-idle>20</pool-max-idle>
        <pool-remove-abandoned>true</pool-remove-abandoned>
        <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
       
        <validation-query>select 1</validation-query>
        <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
        <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
        <pool-test-while-idle>true</pool-test-while-idle>
        <pool-test-on-borrow>false</pool-test-on-borrow>
      </jdbc-datasource>
      </jira-database-config>
  3. Restart JIRA for the changes to take effect.


For more information on this, please see the documentation regarding connecting JIRA to a database.

MySQL Server 5.6 and lower

To resolve issues with the database connection update the dbconfig.xml file with the configuration and restart your JIRA instance.

  1. Locate the dbconfig.xml file ls located under: JIRA_HOME/dbconfig.xml.
  2. Update the dbconfig.xml file to ensure it matches the recommendations in the documentation.
    • An example dbconfig.xml file that contains all required arguments has been provided below:

      <?xml version="1.0" encoding="UTF-8"?>
      <jira-database-config>
        <name>defaultDS</name>
        <delegator-name>default</delegator-name>
        <database-type>mysql</database-type>
        <jdbc-datasource>
          <url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;amp;characterEncoding=UTF8&amp;amp;sessionVariables=storage_engine=InnoDB</url>
          <driver-class>com.mysql.jdbc.Driver</driver-class>
          <username>jiradbuser</username>
          <password>password</password>
          <pool-min-size>20</pool-min-size>
          <pool-max-size>20</pool-max-size>
          <pool-max-wait>30000</pool-max-wait>
          <pool-max-idle>20</pool-max-idle>
          <pool-remove-abandoned>true</pool-remove-abandoned>
          <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
          <validation-query>select 1</validation-query>
          <validation-query-timeout>3</validation-query-timeout>
          <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
          <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
        
          <pool-test-while-idle>true</pool-test-while-idle>
          <pool-test-on-borrow>false</pool-test-on-borrow>
        </jdbc-datasource>
      </jira-database-config>


  3. Restart the JIRA Server for the changes to take effect.

For more information on this, please see the documentation regarding connecting JIRA to a database.

MySQL Server 5.7 and higher

To resolve issues with the database connection update the dbconfig.xml file with the configuration and restart your JIRA instance.

  1. Locate the dbconfig.xml file ls located under: JIRA_HOME/dbconfig.xml.
  2. Update the dbconfig.xml file to ensure it matches the recommendations in the documentation.
    • An example dbconfig.xml file that contains all required arguments has been provided below:

      <?xml version="1.0" encoding="UTF-8"?>
      <jira-database-config>
        <name>defaultDS</name>
        <delegator-name>default</delegator-name>
        <database-type>mysql</database-type>
        <jdbc-datasource>
          <url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;amp;characterEncoding=UTF8&amp;amp;sessionVariables=default_storage_engine=InnoDB</url>
          <driver-class>com.mysql.jdbc.Driver</driver-class>
          <username>jiradbuser</username>
          <password>password</password>
          <pool-min-size>20</pool-min-size>
          <pool-max-size>20</pool-max-size>
          <pool-max-wait>30000</pool-max-wait>
          <pool-max-idle>20</pool-max-idle>
          <pool-remove-abandoned>true</pool-remove-abandoned>
          <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
          
          <validation-query>select 1</validation-query>
          <validation-query-timeout>3</validation-query-timeout>
          <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
          <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
        
          <pool-test-while-idle>true</pool-test-while-idle>
          <pool-test-on-borrow>false</pool-test-on-borrow>    
        </jdbc-datasource>
      </jira-database-config>


  3. Restart the JIRA Server for the changes to take effect.

For more information on this, please see the documentation regarding connecting JIRA to a database.

Oracle Database

To resolve issues with the database connection update the dbconfig.xml file with the configuration and restart your JIRA instance.

  1. Locate the dbconfig.xml file ls located under: JIRA_HOME/dbconfig.xml.
  2. Update the dbconfig.xml file to ensure it matches the recommendations in the documentation.
    • An example dbconfig.xml file that contains all required arguments has been provided below:

      <?xml version="1.0" encoding="UTF-8"?>
      <jira-database-config>
        <name>defaultDS</name>
        <delegator-name>default</delegator-name>
        <database-type>oracle10g</database-type>
        <jdbc-datasource>
          <url>jdbc:oracle:thin:@dbserver:1521:ORCL</url>
          <driver-class>oracle.jdbc.OracleDriver</driver-class>
          <username>jiradbuser</username>
          <password>password</password>
          <pool-min-size>20</pool-min-size>
          <pool-max-size>20</pool-max-size>
          <pool-max-wait>30000</pool-max-wait>
          <pool-max-idle>20</pool-max-idle>
          <pool-remove-abandoned>true</pool-remove-abandoned>
          <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
       
          <validation-query>select 1 from dual</validation-query>
          <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
          <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
        
          <pool-test-while-idle>true</pool-test-while-idle>
          <pool-test-on-borrow>false</pool-test-on-borrow>
        </jdbc-datasource>
      </jira-database-config>


  3. Restart the JIRA Server for the changes to take effect.

For more information on this, please see the documentation regarding connecting JIRA to a database.

PostgreSQL Server

To resolve issues with the database connection update the dbconfig.xml file with the configuration and restart your JIRA instance.

  1. Locate the dbconfig.xml file ls located under: JIRA_HOME/dbconfig.xml.
  2. Update the dbconfig.xml file to ensure it matches the recommendations in the documentation.
    • An example dbconfig.xml file that contains all required arguments has been provided below:

      <?xml version="1.0" encoding="UTF-8"?>
      
      <jira-database-config>
        <name>defaultDS</name>
        <delegator-name>default</delegator-name>
        <database-type>postgres72</database-type>
        <schema-name>public</schema-name>
        <jdbc-datasource>
          <url>jdbc:postgresql://dbserver:5432/jiradb</url>
          <driver-class>org.postgresql.Driver</driver-class>
          <username>jiradbuser</username>
          <password>password</password>
          <pool-min-size>20</pool-min-size>
          <pool-max-size>20</pool-max-size>
          <pool-max-wait>30000</pool-max-wait>
          <pool-max-idle>20</pool-max-idle>
          <pool-remove-abandoned>true</pool-remove-abandoned>
          <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
       
          <validation-query>select version();</validation-query>
          <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
          <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
        
      	<pool-test-while-idle>true</pool-test-while-idle>
          <pool-test-on-borrow>false</pool-test-on-borrow>
        </jdbc-datasource>
      </jira-database-config>


  3. Restart the JIRA Server for the changes to take effect.

For more information on this, please see the documentation regarding connecting JIRA to a database.

Flag Information

Below are the flags that will be reported by this health check, and what checks are made for each flag.

min-evictable-idle-time-millis

This is the minimum amount of time a connection may be idle in the connection pool before it is considered for eviction. This setting is only checked If JIRA is connected to a MySQL Database. If this flag is shown, the MySQL Database configuration does not have this value set.

pool-max-size

This is the maximum connection pool size. The health check confirms that this value is no less than 20. If this flag is shown, adjust the dbconfig.xml to have a greater value for the pool-max-size parameter and restart the JIRA instance.

pool-remove-abandoned

This option allows for the removal of connections that have been considered abandoned. This will prevent situations where the database fails to respond to a requests and all connections in the pool become used. If this flag is shown adjust the dbconfig.xml file accordingly, or see the Resolution section above for examples.

pool-remove-abandoned-timeout

 This the the time in seconds that JIRA will wait before an abandoned connection is removed. The health check confirms that the parameter is set, and the value is not larger than 300 seconds. If this flag is shown adjust the dbconfig.xml file accordingly, or see the Resolution section above for examples.

pool-test-on-borrow

This setting checks if a validation query will be sent when the connection is borrowed from the pool. The health check confirms that this value is set to false to prevent too many validation queries being sent to the database. Please set the pool-test-on-borrow values to false in the dbconfig.xml file, or see the Resolution section above for examples.

pool-test-while-idle

This setting will cause the connection pool to be tested while the connections are idle using the validation query. The health check confirms that this value is set to true to ensure that validation queries are being made. Please set the pool-test-while-idle setting to true in the dbconfig.xml file if the health check reports this flag. See the Resolution section above for examples.

time-between-eviction-runs-millis

The time-between-eviction-runs-millis is the number of milliseconds to wait before running a cleanup on connections ready for eviction. This health check is only ran against databases using MySQL Server and confirms that a value has been set. If you see this flag reported by the health check, update your dbconfig.xml file to include a value for this parameter. S ee the Resolution section above for examples on how to set this value for MySQL.

validation-query

The validation query is the query sent to the database to check the connection is working. The health check confirms that a validation query exists. If the health check reports the validation-query flag, configure a validation query in the dbconfig.xml file. See the Resolution section above for examples appropriate for your specific database.

validation-query-timeout

The validation query timeout is the timeout length of time allowed before the validation query fails. The health check only confirms this value is present on MySQL databases. If the health check reports this flag, configure a validation query timeout as per the documented settings. See the resolution information for more information.

Description

This health check reviews the current database connection settings in use. The check reviews the settings to confirm that an optimal configuration is set. An optimal configuration will improve stability and protect against problems relating to Database Connection Pools when using an External Database (Such as MS SQL, MySQL, Oracle or PostgreSQL). Only JDBC Datasource connections are checked. Embedded Databases (Such as H2) and database configurations relying on a JNDI configuration are not checked.

ProductJira
PlatformServer
Last modified on Aug 11, 2021

Was this helpful?

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