These instructions will help you connect JIRA to an Oracle 10g or 11g database. Oracle 9i is no longer a supported database for use with JIRA and the 11.2.x drivers from Oracle do not support 9i.
On this page:
- Before you begin
- 1. Configure Oracle
- 2. Copy the Oracle driver to your application server
- 3. Configure your application server to connect to Oracle
- 4. Configure the JIRA Entity Engine
- Next steps
- User-contributed notes
Before you begin
Check the compatibility of your Oracle server and driver
Please note that a number of the Oracle server and driver versions cannot be used with JIRA or are inherently unstable. The known issues with Oracle servers and drivers are as follows:
We recommend that you avoid using version 10.2.0.3 of the Oracle server. Oracle server version 10.2.0.3 has been noted to produce occurrences of error ORA-01461. Oracle metalink Note:461670.1 has further details on this Oracle server issue (note, you will need an Oracle support account to view this document).
JIRA customers with this problem have reported that upgrading to Oracle server version 10.2.0.4 resolves the issue.
We recommend that you use the 11.2.x version of the driver for all versions of Oracle (it is backwards compatible). Many other versions of the driver have been noted have problems, such as:
- Version 10.2.0.3.0 of the 10g Release 2 JDBC driver has been noted to produce occurrences of error ORA-01461. Oracle metalink Note:461670.1 has further details on this Oracle server issue (note, you will need an Oracle support account to view this document).
- Version 10.2.0.1.0 of the 10g Release 2 JDBC driver hangs with some databases.
- The 10g Release 1 JDBC driver (10.1.0.4) does not hang, but throws ArrayIndexOutOfBoundsExceptions.
Export your existing JIRA data
1. Configure Oracle
- Create a database user which JIRA will connect as (e.g.
- Create a database for JIRA to store issues in (e.g.
- Ensure that the user has permission to connect to the database, and create and populate tables.
2. Copy the Oracle driver to your application server
- Download the Oracle JDBC driver (from Oracle's site).
- Add the appropriate Oracle JDBC driver jar (
ojdbc5.jarfor JDK 1.5,
ojdbc6.jarfor JDK 1.6) to the
common/lib/directory (for Tomcat), or the relevant
libdirectory in your app server.
3. Configure your application server to connect to Oracle
Tomcat (or JIRA Standalone)
In an editor, open
conf/server.xml (JIRA Standalone) or
conf/Catalina/localhost/jira.xml (regular Tomcat). Locate the section:
(Note: if you can't find a section like this at all, you've probably got the wrong file. Search for mentions of 'jira' in the files under
Replace this section with the following:
Customise the username, password, database server hostname (assumed to be
localhost above, and database name (
If you were previously using hsqldb make sure you have removed have the
timeBetweenEvictionRunsMillis attributes. They will slow JIRA down if present.
JIRA WAR/EAR distribution
If you're deploying JIRA on another application server, you'll need to build a JIRA Webapp from the WAR/EAR distribution. Refer primarily to the application server setup guides for details of configuring your application server.
4. Configure the JIRA Entity Engine
atlassian-jira/WEB-INF/classes/entityengine.xml(if you are using JIRA Standalone) or
edit-webapp/WEB-INF/classes/entityengine.xml(JIRA WAR/EAR), and make the following changes:
- Change the
oracle10g. If you forget to do this and start JIRA, it may create database tables incorrectly. See this page if this happens to you.
- Remove the
- Change the
You should now have an application server configured to connect to a database, and JIRA configured to use the correct database type. If you are using JIRA Standalone, start it up and watch the logs for any errors. If you are using the JIRA WAR/EAR distribution, rebuild and redeploy the webapp in your application server.