Configure a Database datasource
Definition
The Direct Database Connector allows you to declare an access to any relational database reachable from your JIRA server.
Use it if:
You want to query data from a relational database,
You don't have access to the Tomcat file, and are not able to configure a JNDI datasource descriptor.
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:
Datasource | Driver |
|---|---|
PostgreSQL | PostgreSQL JDBC driver (official) |
MySQL | Connector/J (official) |
SQLServer | Microsoft JDBC Driver for SQL Server (official) jTDS JDBC Driver (alternative) |
Oracle | Oracle 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.
If you don't know how to configure a Database datasource - contact a Database Administration (DBA) of your organization.
Timeout
Retrieving data from a database is done in two steps:
Connect - Establishing the connection to the remote database
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:
Connect timeout - A non-configurable 5 seconds timeout applied to the "Connection" step.
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.
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
Troubleshooting
Related troubleshooting articles: