Cloud
Data Center 9.15
Versions

Connecting Jira applications to Oracle

Connecting Jira applications to a database

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

These instructions will help you connect Jira to an Oracle database.

Before you begin

On this page:

1. 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 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

  3. 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 the RESOURCE role grants the SELECT ANY TABLE privilege, then Jira functions may not work as expected. Thus, we recommend that you grant the exact privileges to the user instead.

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

  1. Download the Oracle JDBC driver.
  2. Copy the downloaded .jar file to the lib/ 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.

  1. On the Configure Language and Database screen that appears first, set Database Connection to My own database.
  2. Set Database Type to Oracle.
  3. Fill out the fields as described in the Database connection fields section.
  4. Test your connection and save.

Configuring Jira by using the configuration tool

  1. Run the Jira configuration tool as follows:
  2. Go to the Database tab and set Database type to Oracle.
  3. Fill out the fields as described in the Database connection fields section.
  4. 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.
  5. Restart Jira.

Database connection fields


Setup Wizard / Configuration tooldbconfig.xml

Description

Hostname

Located in the <url> tag (bold text in the following example): url>jdbc:oracle:thin:@ dbserver :1521/ORCL</url>

The name or IP address of the machine that the Oracle server is installed on.
Port

Located in the <url> tag (bold text in example below):
<url>jdbc:oracle:thin:@dbserver: 1521/ORCL</url>

The TCP/IP port that the Oracle server is listening on. The default port number for Oracle is "1521".
SID

Located in the <url> tag (bold text in example below):<url>jdbc:oracle:thin:@dbserver:1521/ ORCL </url>

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 <username> tag (see bold text in example below):
<username> jiradbuser </username>

The user that Jira uses to connect to the Oracle server. You should have created this user in Step 1 of this guide.

PasswordLocated 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 your dbconfig.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. 
Last modified on Jan 16, 2023

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.