Connecting Jira Data Center to Amazon Aurora
These instructions will help you connect Jira to an existing Amazon Aurora PostgreSQL database.
Amazon Aurora is only supported on a Data Center license
Jira Data Center supports the use of a single-writer, PostgreSQL-compatible Amazon Aurora clustered database. A typical production-grade cluster includes one or more readers in a different availability zone. If the writer fails, Amazon Aurora will automatically promote one of the readers to take its place. For more information, see Amazon Aurora Features: PostgreSQL-Compatible Edition.
Before you begin
- Check whether your version of Amazon Aurora is supported. See Supported platforms.
- Shut down Jira before you begin, unless you are running the setup wizard.
1. Create and configure the PostgreSQL database
Jira Data Center specifically supports the use of an Amazon Aurora cluster with the following configuration:
It must have only one writer, replicating to one or more readers.
Your PostgreSQL engine must be version 9.6 or higher.
See Supported platforms for more details.
AWS documentation
Modular Architecture for Amazon Aurora PostgreSQL: a Quick Start that guides you through the deployment of a PostgreSQL-compatible Aurora Database cluster. This cluster has one writer and two readers, preferably in different availability zones.
Upgrading the PostgreSQL DB Engine for Amazon RDS: shows you how upgrade your database engine to a supported version before migrating it to Amazon Aurora.
Migrating Data to Amazon Aurora PostgreSQL: contains instructions for migrating from Amazon RDS to a PostgreSQL-compatibleAmazon Aurora cluster.
Best Practices with Amazon Aurora PostgreSQL: contains additional information about best practices and options for migrating data to a PostgreSQL-compatible Amazon Aurora cluster.
Amazon also offers an AWS Database Migration Service to facilitate a managed migration. This service offers minimal downtime, and supports migrations to Aurora from a wide variety of source databases.
2. Configure your Jira server to connect to your PostgreSQL database
There are two ways to configure your Jira server to connect to your Amazon Aurora database:
- Using the Jira setup wizard — Use this method if you have just installed Jira, and you are setting it up for the first time. Your settings will be saved to the
dbconfig.xmlfile in your Jira home directory. - Using the Jira configuration tool — Use this method if you have an existing Jira instance. Your settings will be saved to the
dbconfig.xmlfile in your Jira home directory.
Instructions for each configuration method
Jira setup wizard
The Jira setup wizard will display when you access Jira for the first time in your browser.
In the first screen, 'Configure Language and Database', set Database Connection to My own database.
Set Database Type to Aurora PostgreSQL 9.6 (DC Only).
Fill out the fields, as described in the Database connection fields section below.
- Test your connection and save.
Jira configuration tool
- Run the Jira configuration tool as follows:
- Windows: Open a command prompt and run
config.batin thebinsub-directory of the Jira installation directory. Linux/Unix: Open a console and execute
config.shin thebinsub-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
- Navigate to the Database tab
- Set Database Type to Aurora PostgreSQL 9.6 (DC Only).
- Fill out the fields, as described in the Database connection fields section below.
- Test your connection and save.
- Restart Jira.
Database connection fields
| Setup Wizard / Configuration Tool | dbconfig.xml tag | Description |
|---|---|---|
| Hostname | Located in the | The name or IP address of the machine that the PostgreSQL server is installed on. |
| Port | Located in the <url> tag (bold text in example below):<url>jdbc:postgresql://dbserver:5432/jiradb?targetServerType=master</url> | The TCP/IP port that the PostgreSQL server is listening on. You can leave this blank to use the default port. |
| Database | Located in the <url> tag (bold text in example below):<url>jdbc:postgresql://dbserver:5432/jiradb?targetServerType=master</url> | The name of your PostgreSQL database (into which Jira will save its data). You should have created this in Step 1 above. |
| Username | Located in the | The user that JIRA uses to connect to the PostgreSQL server. You should have created this in Step 1 above. |
| Password | Located in the <password> tag (see bold text in example below):<password>jiradbuser</password> | The user's password — used to authenticate with the PostgreSQL server. |
| Schema | Located in the <schema-name> tag (see bold text in example below):<schema-name>public</schema-name> | The name of the schema that your PostgreSQL database uses. |
Schema requirements
PostgreSQL 7.2 and later require a schema to be specified in the <schema-name/> element. If your PostgreSQL database uses the default 'public' schema, this should be specified in the <schema-name/> element as shown below. Ensure that your database schema name is lower-case, as JIRA cannot work with PostgreSQL databases whose schema names contain upper-case characters.
Sample dbconfig.xml file
For more information about the child elements of <jdbc-datasource/> beginning with pool in the dbconfig.xml file below, see Tuning database connections.
<?xml version="1.0" encoding="UTF-8"?>
<jira-database-config>
<name>defaultDS</name>
<delegator-name>default</delegator-name>
<database-type>postgres72</database-type>
<schema-name>public</schema-name>
<jdbc-datasource>
<url>jdbc:postgresql://dbserver:5432/jiradb?targetServerType=master</url>
<driver-class>org.postgresql.Driver</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 version();</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-on-borrow>false</pool-test-on-borrow>
<pool-test-while-idle>true</pool-test-while-idle>
</jdbc-datasource>
</jira-database-config>
3. Start Jira
You should now have Jira Data Center configured to connect to your Amazon Aurora database. The next step is to start it up!
Congratulations, you now have Jira Data Center connected to your PostgreSQL database.