This page describes how to upgrade JIRA. Before you start, you should review the release notes and upgrade guide for the version you are upgrading to.

On this page:

Overview

In summary, the method for upgrading JIRA is to set up a new instance of JIRA, and then migrate your existing JIRA data into the new JIRA instance. There are two variations of this method, the difference being in how you choose to migrate your existing JIRA data.

"XML backup/restore" method (recommended)

With this method, you back up your data as an XML file from your existing JIRA instance, back up your attachments, and then restore that data into the new JIRA instance. The new JIRA will create the database structure (tables and indexes) before importing the data; or,

"Connect JIRA to a copy of your old database" method

With this method, you take a copy of your existing JIRA database and configure the new JIRA to use the copied database. When you first start up the new JIRA it will upgrade the database to the structure needed for the new JIRA version.

Which method should I use to migrate my data into my new JIRA?

We recommend that you use the "XML backup/restore" method, as the "Connect JIRA to a copy of your old database" method has the following restrictions:

The "Connect JIRA to a copy of your old database" method can be useful for extremely large installations, where the recommended method of "XML backup/restore" would take too long.

The upgrade process

Overall, the process to upgrade JIRA takes five steps (four steps, if you are not performing an XML backup/restore to migrate your existing JIRA data):
Set up a new instance of JIRA:
1. Install the new instance of JIRA.
2. Configure your new JIRA to have the same configuration as your old JIRA.
Migrate your existing JIRA data:
3. Set up a new database.
4. (If doing an "XML backup/restore" method) Export your data from your old JIRA.
5. Start the new JIRA (including the import of your old data into your new JIRA instance, if doing an XML backup/restore).

Before you begin

Set up a new instance of JIRA

If you are upgrading your version of JIRA, you will need to set up a new instance of JIRA that you can migrate your existing data into. This involves installing a new empty instance of the desired version of JIRA and applying configuration changes to match the configuration of your old instance of JIRA.

1. Install the new version of JIRA

Download and unpackage the JIRA distribution you require, JIRA Standalone or JIRA EAR/WAR, to a new directory. Do not overwrite your old JIRA instance.

2. Configure your new JIRA to have the same configuration as your old JIRA

You may have modified a number of configuration files in your existing JIRA instance. You need to make the same changes in your new JIRA instance. However, you cannot simply copy the file from your old instance, as the format may have changed from the old version to the new one. You need to manually edit all of the relevant lines in the new file, applying any changes you previously made to the file in your existing JIRA.

The following files are commonly modified in JIRA installations:

File

JIRA Standalone location

JIRA EAR WAR location

Description

entityengine.xml

atlassian-jira/WEB-INF/classes

edit-webapp/WEB-INF/classes

Used to configure the JIRA entity engine for your database type. Refer to the Configure the JIRA Entity Engine section of your database guide.

osuser.xml

atlassian-jira/WEB-INF/classes

webapp/WEB-INF/classes

Modified if you are integrating LDAP with JIRA, or if you are using a custom form of external user management or user authentication.

jira-application.properties

atlassian-jira/WEB-INF/classes

webapp/WEB-INF/classes

Advanced JIRA configuration properties

server.xml

conf

File and location varies per application server

Modified when connecting JIRA to a database

In addition to the above files, there are several other configuration changes that you may have to migrate:

Migrating your existing JIRA data into your new JIRA instance

The process for migrating your existing JIRA data into your new JIRA instance generally involves setting up a new/copied database, configuring it to work with your new instance of JIRA and populating it with data, if required. As previously described, you can choose to migrate your existing data by XML backup/restore (recommended) or by connecting JIRA to a copy of your old database.

3. Set up a new database

The first step of migrating your existing data into your new JIRA instance is to set up a new database. If you are using the XML backup/restore method, you need to set up a new empty database. If you are using the Connect JIRA to a copy of your old database method, then you must take a copy of your old database for the migration. You will then need to configure JIRA to use your new database and if you are using JIRA EAR/WAR, build and deploy the JIRA web application.

3.1a ("XML backup/restore" method only) Create a new empty database

If you are migrating your data to the new JIRA using the XML backup/restore method, create a new database (note, you do not need to create a new database if you are using the embedded HSQL database). For example, if you are using a database 'jiradb' with your existing installation, and you are upgrading to JIRA 3.12, create database 'jiradb_312' with identical access permissions. Consult with your DBA if you need assistance with this.

3.1b ("Connect JIRA to a copy of your old database" method only) Take a copy of your existing database

If you are using the Connect JIRA to a copy of your old database method, it is critical that you take a copy of your existing database for the data migration. Do not just connect the new JIRA to your existing database, as it will be upgraded to the format required by the new JIRA version. Hence, if any problems occur with your upgrade, you will not be able to revert to using your old JIRA.

If you are migrating your data to the new JIRA using the Connect JIRA to a copy of your old database method, follow the steps below to create a copy of your existing database:

  1. Make your existing JIRA read-only or shutdown your existing JIRA, so that users cannot make changes until the upgrade is complete. If you do not do this, you will lose any updates that users make from this point until the upgrade is complete.
  2. Use the vendor's tools for your database to make a copy of your existing JIRA database. Consult with your DBA if you need help to do this.
  3. Check your version of JIRA. If you are upgrading from 3.6.5 (or earlier) to 3.7 or later, JIRA will not be able to update your database automatically when you start the new instance (see 'Start the new JIRA' section below). This is due to the large number of database changes between 3.6.5 and 3.7. You will need to manually upgrade your copied database to the 3.7 schema instead.

3.2. Configure JIRA to use your new database

The following instructions describe how to configure JIRA to use your new database. The steps differ depending on whether you are using JIRA Standalone or JIRA EAR/WAR:

3.3 (JIRA EAR/WAR only) Build the JIRA web application and deploy it to your application server

If you are using JIRA EAR/WAR, complete the setup of your new database by building your new JIRA web application and deploying it to your server. You can do this by running either the build.bat file (Windows) or the build.sh file (Unix). Read your application server guide to see if there are any server-specific instructions for building the web application. For example, there may be parameters you need to pass to the build script.

4. ("XML backup/restore" method only) Export your data from your old JIRA

If you are using the XML backup/restore method, you can now export your data from your existing JIRA instance in preparation for the import into your new database. To export your existing JIRA data into a backup file, follow the steps below:

  1. Ensure that users cannot update your existing JIRA while you perform the XML backup, so that your backup will not contain inconsistent data. There are two ways that you can do this:
  2. After you have ensured that users cannot update your existing JIRA, generate the XML backup. Read these instructions on 'Backing up data' for details of how to do this. Please note, you will also need to back up your attachments as described in the 'Backing up data' document.
  3. Remember to restore JIRA access appropriately when the upgrade is complete.

5. Start the new JIRA

The final step of upgrading your JIRA is to start your new JIRA instance and, if you are using the XML backup/restore method, import the data from your old JIRA instance. As previously described, starting your new JIRA instance will automatically update your new/copied database.

  1. If you haven't already done so, shut down your old JIRA instance by stopping the JIRA server.
  2. Start up your new instance of JIRA,

Starting up JIRA using Tomcat If you are using Tomcat with your installation of JIRA (note, JIRA Standalone ships with Tomcat by default), delete the Tomcat work directory before restarting JIRA. If you do not do this, users may encounter errors when they try to display JIRA pages.

5.1. ("XML backup/restore" method only) Import your old JIRA data into your new JIRA

If you are migrating your data to the new JIRA using the XML backup/restore method, you will need to import the data from your old instance into your new JIRA instance after you have successfully started it. You will need the backup file of data from your old JIRA that you created earlier in these instructions.

To import your old JIRA data into your new JIRA,

  1. Access JIRA via your web browser. You will see the Setup Wizard.
  2. Click the 'Import Existing Data' link.
  3. The 'Import Existing Data' page will display.
  4. Restore the attachments directory that you backed up in step 4.2 previously, into the attachments directory of your new JIRA.

5.2 Post-startup checks and tasks

We highly recommend that you perform the following checks and tasks after you have started your new instance of JIRA:

  1. Check your server logs for error messages, even if JIRA appears to be running correctly. If there are any errors there that you cannot resolve, create a support case in https://support.atlassian.com, attach your log file and we will advise you on the errors.
  2. If you were previously using External User Management, enable it in the new JIRA instance.
  3. If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA.
  4. Enable email, if you disabled it during testing.
  5. If you migrated any customisations from your old JIRA to the new JIRA, ensure that they are tested thoroughly.

Congratulations! You have completed your upgrade of JIRA.

Troubleshooting