This page last changed on Oct 05, 2009 by alui.
This document applies to Oracle 10g and 11g. Oracle 9i is no longer a recommended database for use with JIRA and the 11.2.x drivers from Oracle do not support 9i.
 | Please note, a number of the Oracle server and driver versions cannot be used with JIRA or are inherently unstable. The section on Oracle server and driver compatibility below lists the known issues with Oracle servers and drivers. |
On this page:
Before you begin
|
Check the compatibility of your Oracle server and driver
Oracle server:
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.
Oracle driver:
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
If you are already using JIRA, create an export of your data as an XML backup. You will then be able to transfer data from your old database to your new database, as described in Switching databases. |
1. Configure Oracle
|
- Create a database user which JIRA will connect as (e.g. jirauser).
- Create a database for JIRA to store issues in (e.g. jiradb).
- 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.jar for JDK 1.5, ojdbc6.jar for JDK 1.6) to the common/lib/ directory (for Tomcat), or the relevant lib directory 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:
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
username="sa"
password=""
driverClassName="org.hsqldb.jdbcDriver"
url="jdbc:hsqldb:${catalina.home}/database/jiradb"
minEvictableIdleTimeMillis="4000"
timeBetweenEvictionRunsMillis="5000"
maxActive="20" />
(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 conf/).
Replace this section with the following:
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
username="[enter db username]"
password="[enter db password]"
driverClassName="oracle.jdbc.driver.OracleDriver"
url="jdbc:oracle:thin:@localhost:1521:jiradb"
maxActive="20"/>
Customise the username, password, database server hostname (assumed to be localhost above, and database name (jiradb above).
If you were previously using hsqldb make sure you have removed have the minEvictableIdleTimeMillis and 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
|
- Edit 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:
- If you are using JIRA WAR/EAR, your application server may require other changes to entityengine.xml (e.g. to customise the jndi-jdbc tag). Please refer to the documentation for your application server for details.
|
Next steps
|
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. |
User-contributed notes
|