Configure a Database datasource

Table of contents


The Direct Database Connector allows you to declare an access to any relational database reachable from your JIRA server.

Use it if:

Databases supported by Elements Connect

  • Microsoft SQL Server
  • Oracle
  • PostgreSQL
  • MySQL

Your database is not in this list? Use a JNDI connection instead, which offers a wider databases support and provides some performance benefits.

Database driver

Elements Connect uses the JDBC drivers available in Jira classpath. Depending on your Jira configuration, only one driver could be available.

If you want to configure a connection to another type of database you must make the JDBC driver available.

This task requires 3 steps:

1 - Download the driver

Download the driver corresponding to your database:


PostgreSQL JDBC driver (official)


Connector/J (official)


Microsoft JDBC Driver for SQL Server (official)

jTDS JDBC Driver (alternative)

OracleOracle database JDBC driver (official)

If you datasource driver is not in this list, it does not means that it does not exists - just google it 'MY_DATABASE jdbc driver'.

2 - Add the driver to the classpath

Copy the .jar file into:

  • the <TOMCAT_HOME>/lib folder for WAR installation.
  • the <JIRA_APP>/lib folder for standalone installation. 

3 - Restart Tomcat

Tomcat must be restarted once in order to have the driver loaded in the classpath.

Datasource configuration

Elements Connect offers two configuration modes for Database datasources, Simple and Advanced.

Simple configuration

With this mode, you'll be guided step by step by the form. It suits most of the use cases.
Form options may vary depending on the selected database type.

From the parameters you've set, Elements Connect will generate the connection URL to the database.
If your database requires some specific parameters in the URL, you must use the Advanced mode.

(info) If you don't know how to configure a Database datasource - contact a Database Administration (DBA) of your organization.


Retrieving data from a database is done in two steps:

  1. Connect - Establishing the connection to the remote database
  2. Read - Waiting for the remote database to return the result of a query

Some queries may take a long time to return from the remote database because of the query itself or unusual load of the remote database.
A long delay can have a negative impact on Jira load times, whether a user is editing or viewing an Issue.

That's why two timeouts are set on Database datasources:

  1. Connect timeout - A non-configurable 5 seconds timeout applied to the "Connection" step.
  2. Read timeout - A configurable timeout with a default value of 10 seconds applied to the "Read" step
    This value can be configured from the datasource configuration, from 1 second to 600 seconds (10 minutes).
    The lower this value, the less impact a slow remote server might have on the Jira load time.

When a timeout is reached, the query to the remote database is aborted.
Elements Connect behavior depends on the context:

  • Field edit: no option available in the field editor
  • Issue display: you'll see the field "stored" value (the field key) on which the "No result template" is optionally applied

Advanced  configuration

This mode requires more DB expertise but it also offers more control since you can configure the connection URL yourself.
Use it if the Simple mode does not cover your use case.

(info) If you don't know how to configure a Database datasource - contact a Database Administration (DBA) of your organization.

Edit configuration

For security reasons, the database password will not appear in the edit configuration screen.
If you want to change the database password you can click on Change password. A field will appear to let you enter a new one.


If you do not click on "Change password" link while editing, Test connection action will use the password stored in database.

If you click on "Change password" and leave the field empty, Test connection action will use an empty password.

Field configuration

See Field configuration


Related troubleshooting articles: