Search the JIRA 5.0.x Beta and RCs Documentation:

Index
Downloads (PDF, HTML & XML formats)
Other versions

This documentation relates to JIRA 5.0.x Beta and RCs only.
The latest official version is JIRA 4.4.x
If you are using JIRA 4.4.x either view this page in the JIRA 4.4.x documentation or visit the JIRA 4.4.x documentation home page.
Skip to end of metadata
Go to start of metadata

These instructions will help you connect JIRA to an Oracle 11g database.

(info) Please Note:

  • If you are setting up a completely new JIRA installation, the JIRA Setup Wizard will configure a Oracle database connection for you.
  • Oracle 9i is no longer a supported database for use with JIRA and the 11.2.x drivers from Oracle do not support 9i.

1. Before You Begin

1.1 Are You Migrating JIRA to Another Server?

If you are Migrating JIRA to Another Server, 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.2 Shut Down JIRA

On this page:

2. Configure Oracle

  1. Ensure that you have a database instance available for JIRA (either create a new one or use an existing one).

  2. Within that database instance, create a user which JIRA will connect as (e.g. jiradbuser). (tick) Remember this database user name, as it will be used to configure JIRA's connection to this database in subsequent steps.
    (info) When you create a user in Oracle, Oracle will create a 'schema' automatically.
    (info)When you create a user, the tablespace for the table objects must be specified.

  3. Ensure that the user has the following permissions:

3. Copy the Oracle JDBC Driver to Your Application Server (JIRA WAR Only)

(warning) Skip this step if you installed a 'Recommended' distribution of JIRA, which (unlike JIRA WAR) includes the Oracle JDBC driver.

  1. Download the Oracle JDBC driver (from Oracle's site).
  2. Add the appropriate Oracle JDBC driver jar (ojdbc5.jar for JDK 1.5, ojdbc6.jar for JDK 1.6) to the lib/ directory.

Please note that a number of the Oracle JDBC driver versions cannot be used with JIRA or are inherently unstable. The known issues with Oracle drivers are as follows:

  • We recommend that you use the 11.2.x versionof the driver for all versions of Oracle (it is backwards compatible). Many other versions of the driver have been noted to 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. The Oracle Support site has further details on this Oracle server issue, although you will need an Oracle support account to access this site.
    • 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.

4. 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:

(info) Please Note:

4.1 Connecting JIRA to Oracle Using the JIRA Configuration Tool

(warning) The JIRA Configuration Tool is not available with JIRA WAR distributions.

To start the JIRA Configuration Tool:

(info) Please Note: You may need to set the JAVA_HOME environment variable to run the JIRA Configuration Tool. See Installing Java for details.

To connect JIRA to Oracle using the JIRA Configuration Tool:

  1. Click the 'Database' tab.
  2. From the 'Database type' drop-down choose 'Oracle'.
    (info) The JIRA Configuration Tool will display your current database configuration settings if any are already set.
  3. Fill in the connection details for your Oracle database.
    • 'Hostname' — The name or IP address of the machine that the Oracle server is installed on.
    • 'Port' — The TCP/IP port that the Oracle server is listening on. The default port number for Oracle is '1521'.
    • 'SID' — The Oracle 'System Identifier'. The default value for most Oracle servers is 'ORCL'. If you are using the Oracle Express Edition, this will be 'XE'.
    • 'Username' — The user that JIRA uses to connect to the Oracle server.
    • 'Password' — The user's password to authenticate with the Oracle server.
  4. JIRA keeps a pool of database connections open to the database server. You can set the maximum size of this pool in the 'Pool Size' text field.
  5. After typing in your settings, click the 'Test Connection' button to test the connection settings. The tool will attempt to connect to the database, and give a message with the results.
  6. Click 'Save' to save your settings when you are done.
    (info) Please Note:
    • The JIRA Configuration Tool will save your database configuration to a dbconfig.xml file in your JIRA Home Directory.
    • If you had previously specified any additional custom settings while manually configuring JIRA with Oracle below (for example, adding the <connection-properties>SetBigStringTryClob=true</connection-properties> element to your dbconfig.xml file), these custom settings will be deleted upon clicking the 'Save' button and you will need to reinstate them manually.
    • JIRA must be restarted for your new settings to take effect.

Congratulations — you have finished! Proceed to 'Next Steps' below.

4.2 Connecting JIRA to Oracle Manually

  1. Edit the dbconfig.xml file at the root of your JIRA Home Directory.
    (info)If this file does not exist, create the file, copy and paste the example XML code below into this file and edit the pasted XML as required.

    Please Note:

    Ensure that the <database-type/> element's content specifies your type of database, as shown below. If you forget to do this and you start JIRA, your database tables may be created incorrectly. Refer to our Incorrect database type specified documentation if this happens to you.

    (warning) When editing your dbconfig.xml file, escape any '&' characters by adding 'amp;' to the end of each one.

    (info) On a default Oracle server installation, your <url/> element's content might look similar to — jdbc:oracle:thin:@dbserver:1521:ORCL

  2. Save your edited dbconfig.xml file (at the root of your JIRA Home Directory).
    (info) JIRA must be restarted for your new settings to take effect.

(minus) Please Note:

  • If you start experiencing 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 your dbconfig.xml file. Adding this connection property may overcome these problems. Be aware that you will need to restart JIRA for this setting to take effect.

5. Next steps

You should now have JIRA configured to connect to your Oracle database. The next step is to start it up!

  • If you are using a 'recommended' distribution of JIRA, start it up and watch the logs for any errors.
  • If you are using the JIRA WAR distribution, rebuild and redeploy the webapp in your application server.

Installation notes

Please see JIRA and Oracle.

12 Comments

Hide/Show Comments

  1. Nov 02, 2010

    Mladen Maravic

    There is an known bug (JRA-19893) when using JIRA and Oracle. To avoid the bug, add the following trigger to the PROJECTVERSION table:

    See the issue for more details.

  2. Feb 08, 2011

    Anonymous

    hello. I'm attempting to create the connection file. The test is successful. When I save I recieve the following error:

    ..\atlassian-jira\WEB-INF\classes\Jira-application.properties (Access is denied)

    I have administrator priveliges on the server. Suggestions?


    1. Aug 08, 2011

      Anonymous

      I had the same problem.  And I fixed it by running the config.bat as administration and then it works perfectly.  Apparently this is only would happen in Windows 7. :(

      1. Feb 03, 2012

        Anonymous

        Awesome!! This helped me. 

  3. Feb 09, 2011

    Anonymous

    this is incomplete. there is a change that needs to be made in entityengine the database. This page http://confluence.atlassian.com/display/JIRA/Configuring+the+Entity+Engine+for+JIRA sheds some light but still not clear exactly what needs to be changed when the database is changed.

  4. Mar 10, 2011

    Anonymous

    I having some problems after done these configurations. When i started JIRA again, it returns me an error:

    Error occurred while starting Plugin Manager. org.ofbiz.core.entity.GenericEntityException: while inserting: [GenericEntity:PluginVersion][id,null][created,2011-03-10 17:22:27.536][name,com.atlassian.gadgets.directory][key,com.atlassian.gadgets.directory][version,0.0] (SQL Exception while executing the following:INSERT INTO pluginversion (ID, pluginname, pluginkey, pluginversion, CREATED) VALUES (?, ?, ?, ?, ?) (ORA-01950: não há privilégios no tablespace USERS' ))

    Anyone with the same problem? what should i do?

  5. Mar 28, 2011

    Anonymous

    Hello All,

            I have an oracle database created and I have made the changes according to the document above,

    in the server.xml<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"username="user"password="password123"driverClassName="oracle.jdbc.OracleDriver"url="jdbc:oracle:thin:@rpc7467:1521:JIRADEV"connectionProperties="SetBigStringTryClob=true"maxActive="20"/>

    in my  entityengine.xml I have done this

    <datasource name="defaultDS" field-type-name="oracle10g" <---- I am actually using oracle 11 g I think it is
          <!- Changed field-type-name from hsql ->
         <!-  schema-name="public" -><!- Turn this on if going back to original configuration ->

    I am hoping I have done this right as my Jira is throwing off errors when I try and start it. The tablespace name as I understand is USERS .....

    Thank you for your help in advance.
    Michael

  6. Mar 29, 2011

    Anonymous

    I am sorry but How do you create the new db for Oracle there is no instructions here on how to create a new db from scratch to import your data to? Or am I missing something in this documentation?

    This doesn't make sense all I see is migrating to a new db ...... How is the db created ..... this does not make sense to me ....

    Michael

    1. Aug 30, 2011

      Anonymous

      Michael, you need to create the db yourself ( see Oracle's documentation and use the Oracle dbca tool if you want a wizard to do it).

      Create the username yourself,either in some SQL tool like sqlplus or through enterprise manager.

      The Jira installation process will create the schema (the tables, indexes, core data etc) with this username in the database. Some other databases eg MYSQL refer to the schema as the database. Don't get them confused.

  7. Sep 15, 2011

    Anonymous

    Are there recommendations for the size of the database that should be allocated?

  8. Oct 12, 2011

    Anonymous

    You can't just "create a user" in Oracle and have it work; the user must be granted the proper subset of several hundred privileges.What privileges are needed by the Oracle user that owns the Jira objects?

    1. Oct 12, 2011

      Anonymous

      Oh sorry, now I see it, under "Configure Oracle"...I wasn't expecting it under that heading, was expecting to see a "Create Oracle user" heading...