Connecting Jira applications to Oracle
1. Configure Oracle
- Ensure that you have a database instance available for Jira — either create a new one or use an existing one.
Within that database instance, create a user which Jira will connect to. For example,
jiradbuser
.
Make sure that you remember this database user name as it will be used to configure Jira's connection to this database in the following steps.create user <user> identified by <user_pass> default tablespace tablespace_name> quota unlimited on <tablespace_name>;
When you create a user in Oracle:
- Oracle will create a "schema" automatically
the tablespace for the table objects must be specified
Ensure that the user has the following privileges:
grant connect to <user>; grant create table to <user>; grant create sequence to <user>; grant create trigger to <user>;
It is critically important that the user is granted the exact privileges as indicated above. Jira requires only these privileges — if either less or more than these privileges are applied, some Jira functions may not work properly.
Simply put, for Jira functions to work as expected, we advise that you grant specific privileges to the user, and not assign a role to the user.
For example, if you grant the
RESOURCE
role to a user, and theRESOURCE
role grants theSELECT ANY TABLE
privilege, then Jira functions may not work as expected. Thus, we recommend that you grant the exact privileges to the user instead.- Ensure that the database is configured to use the same character encoding as Jira. The recommended encoding is AL32UTF8 (the Oracle equivalent of Unicode UTF-8).
2. Download the Oracle JDBC driver
Download the right JDBC driver for your Oracle version:
- Download the Oracle JDBC driver.
- Copy the downloaded
.jar
file to thelib/
directory in the Jira installation directory.
For more information on supported drivers, see Supported platforms.
3. Configure your Jira Server to connect to your Oracle database
There are two ways to configure your JIRA server to connect to your Oracle database:
- By using the Jira setup wizard. Use this method if you have just installed Jira and are setting it up for the first time. Your settings will be saved to the
dbconfig.xml
file in your Jira home directory. - By using the Jira configuration tool. Use this method if you have an existing JIRA instance. The settings will be saved to the
dbconfig.xml
file in your Jira home directory.
Configuring Jiraby using the setup wizard
You'll see the Jira setup wizard when you access Jira for the first time in your browser.
- On the Configure Language and Database screen that appears first, set Database Connection to My own database.
- Set Database Type to Oracle.
- Fill out the fields as described in the Database connection fields section.
- Test your connection and save.
Configuring Jira by using the configuration tool
- Run the Jira configuration tool as follows:
- Windows: Open a command prompt and run
config.bat
in thebin
sub-directory of the Jira installation directory. Linux/Unix: Open a console and execute
config.sh
in thebin
sub-directory of the Jira installation directory.This command might fail with the error as described in Unable to Start Jira applications Config Tool due to No X11 DISPLAY variable was set error. If it happens, refer to this article for the workaround.
- Windows: Open a command prompt and run
- Go to the Database tab and set Database type to Oracle.
- Fill out the fields as described in the Database connection fields section.
- Test your connection and save. Any custom settings specified while manually configuring Jira with Oracle (e.g., adding the
<connection-properties>SetBigStringTryClob=true</connection-properties>
) will be deleted. You will need to reinstate them manually. - Restart Jira.
Database connection fields
Setup Wizard / Configuration tool | dbconfig.xml | Description |
---|---|---|
Hostname | Located in the | The name or IP address of the machine that the Oracle server is installed on. |
Port | Located in the | The TCP/IP port that the Oracle server is listening on. The default port number for Oracle is "1521". |
SID | Located in the | The Oracle "System Identifier". The default value for most Oracle servers is "ORCL". Note that Jira will not work on Oracle Database Express Editions. |
Username | Located in the | The user that Jira uses to connect to the Oracle server. You should have created this user in Step 1 of this guide. |
Password | Located in the <password> tag (see bold text in example below):<password> jiradbuser </password> | The user's password that's used for authentication with the Oracle server. |
Sample dbconfig.xml file
For more information about the child elements of <jdbc-datasource/>
beginning with pool
in the dbconfig.xml
file above, see Tuning database connections.
<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>
Both the Jira setup wizard and database configuration tool also add the element <validation-query>select 1</validation-query>
to the dbconfig.xml
file, which is usually required when running Jira with default MySQL installations. See Surviving connection closures for details.
4. Start Jira
You should now have Jira configured to connect to your Oracle database. The next step is to start it up!
Congratulations, you now have Jira connected to your Oracle database.
Known issues and troubleshooting
- If you face problems when dealing with custom workflows or working with issues that have long descriptions, comments or custom field values, try adding the element
<connection-properties>SetBigStringTryClob=true</connection-properties>
as a child of the</jdbc-datasource>
element in yourdbconfig.xml
file. This connection property may solve the encountered problems. You'll need to restart Jira afterward. - Consider that the Oracle JDBC driver sets the collation for the connection according to the language settings for the JVM. Because of this, for certain languages (for example German or French), the collation for the Oracle connection can be other than the expected “BINARY". For this reason, database results might be sorted in an unexpected order, and it can also trigger a health check warning in Jira. Check the Oracle knowledge base for troubleshooting tips.