Upgrading JIRA

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:

• JIRA may not be able to automatically update the database if you connect a copy of your old database to your new JIRA, if there have been significant changes to the database scheme between versions. This currently applies for upgrades from JIRA 3.6.x or older to JIRA 3.7 or later. See this page for details.
• You may miss out on any performance improvements that we have added to the database between versions. In particular, if we have added new database indexes between versions, these indexes will not be applied if you connect your new version of JIRA to a copy of your old database.

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

• Test first! — We strongly recommend that you carry out all of the following upgrade instructions in a test environment first. Do not upgrade your production JIRA until you are satisfied that the upgrade has been successful in your test environment. If you have any problems with your test upgrade that you cannot resolve, create a support case in https://support.atlassian.com so that we can help you resolve the problems with the upgrade.
• If you have any problems during the upgrade of your production JIRA, do not allow your users to start using the new (upgraded) instance. Instead continue to use your old instance. This will help ensure that you do not lose production data. Create a support case in https://support.atlassian.com so that we can help you resolve the problems with the upgrade.
  

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:

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

• Using JIRA with Atlassian's Crowd — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
• Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA memory.
• Plugins — For any plugins that you had installed in your old JIRA:
  1. Download the plugin version for your new version of JIRA from the JIRA Extensions site.
  2. Install the JAR file(s) in your new JIRA, and carry out any other required installation for the plugin.
  3. If the plugin has a properties file, apply the same changes to it as you had in the old properties file (don't just copy over the old properties file).
• Customisations — If you had made any customisations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organisation who made the customisations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your new JIRA).
• Running JIRA on a different port — If your new instance of JIRA is installed on the same machine as your old JIRA, make sure it is running on a different port. For JIRA Standalone, refer to Changing JIRA Standalone's Port. For JIRA EAR/WAR, consult your application server documentation.
• Disabling email access — If necessary, disable email access in your new JIRA instance, to prevent inadvertent SMTP/POP/IMAP access while testing.
• Character encoding — Please ensure that character encoding (ie. locale) is the same on the new and old locations. You may have problem with encoding of the file names, if attachments are moved between two system with incompatible encoding.
• (JIRA EAR/WAR only) Configuring your application server — If you are running JIRA EAR/WAR, read the latest instructions for your application server and perform any necessary configuration steps. If your application server needs extra libraries to run JIRA, the extra libraries currently in your application server for the old JIRA may be outdated. Make sure you get the extra libraries needed for your new version of JIRA.

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

• JIRA Standalone(please note, these instructions do not apply if you are using the embedded HSQL database with JIRA Standalone. We strongly recommend that you do not to use the HSQL database in production):# Reapply the modifications you made to the conf/server.xml file in your old JIRA Standalone to get your new JIRA Standalone to use your database, but substitute the new database name (*jiradb_312 in the above example) in the JDBC URL.
  1. Read the latest instructions for your particular database and perform any necessary steps. This will include copying the JDBC driver jar file from the common/lib directory of your old JIRA Standalone to your new JIRA Standalone.
• JIRA EAR/WAR:
  1. Follow the instructions for your application server and database to make any changes needed to configure the database connection, including copying over the JDBC driver and setting the JDBC URL.

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:
   • Make JIRA inaccessible: Shut down JIRA, start it on a different port to the one that JIRA usually runs on and do the backup there. Please note, no-one will be able to access JIRA while it is running on a different port during the backup, even to read issues; or,
   • Make JIRA read-only: In your database, remove 'write' permissions from the database user (e.g. jirauser) that JIRA uses. If you do this, users will be able to read issues but will not be able to update them during the backup. For details, please see Making database read-only for upgrade backups. Leave your existing JIRA inaccessible or read-only until the upgrade is completed successfully. You may want to set a banner to warn users that JIRA will be inaccessible/read-only while an upgrade is performed.
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,
   • JIRA Standalone: Follow the Starting JIRA instructions.
   • JIRA EAR/WAR: Follow the instructions for starting JIRA for your application server.

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.
   • In the 'File name' field, specify the XML backup file you created previously.
   • In the 'Index Location' field, specify a different directory from your old JIRA.
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

• If the upgrade fails for any reason, revert to using your old JIRA. Create a support case in https://support.atlassian.com and attach your log file, so that we can help you resolve the problems with the upgrade.
• If your XML import fails with an error message indicating an invalid XML character, use our XML cleaner utility.
• If you are upgrading JIRA WAR on Tomcat, and installing JIRA in the same application server, delete Tomcat's work directory to prevent stale JSPs from being cached.