Preparing Jira for the 9.4 upgrade

Archiving issues is the easiest way to reduce the size of the index because archived issues aren’t indexed. Select non-critical issues for archiving because they won’t be visible to users right after the upgrade. You’ll unarchive and reindex them later on, in upgraded Jira.

Overview

Archived issues won’t change until you upgrade to the new version. After upgrading, you'll perform an initial reindex, which will be much shorter without the archived issues. Once you have a working index and open Jira to your users, you can restore as many of the archived issues as you need and reindex Jira again. The second reindex will take more time but you'll perform it on a single node, without shutting down Jira to your users.

After the upgrade, archives issues will be read-only and accessible via a direct link. Your users won’t be able to search for them until the second reindex, that’s why you should identify issues that can be archived and aren’t critical. To learn more about how archived issues will behave after the upgrade, see Archiving an issue

Before you begin

Identifying issues to be archived

Identify issues you won’t need right after the upgrade. It’s not only about the number of issues, but mostly about their content: attachments, work logs, custom fields, history, or comments.

The more content an issue has, the more it affects reindex. You can select any issues, but the easiest way would be to sort out the issues your users will need right after the upgrade and archive the rest.

Creating an SQL query to archive issues

Once you’ve identified issues for archiving, you should create an SQL query. Here are some example queries that we’ve built based on the PostgreSQL database.

update jiraissue 
	set 
		archived='Y', 
		archivedby='admin', 
		archiveddate=current_timestamp 
	where id in (
		select 
			i.id 
		from jiraissue i 
		where i.created < timestamp '2022-01-01'	
);

update jiraissue 
	set 
		archived='Y', 
		archivedby='admin', 
		archiveddate=current_timestamp 
	where id in (
		select 
			i.id 
		from jiraissue i 
		where i.updated < (current_timestamp - interval '2 year')	
);

update jiraissue 
	set 
		archived='Y', 
		archivedby='admin', 
		archiveddate=current_timestamp 
	where id in (
		select 
			i.id 
		from jiraissue i 
		inner join project p on i.project = p.id
		inner join label l on l.issue = i.id
		where UPPER(p.pkey) = 'JIRA' 
			and l.label = 'archive'
			and i.created  between timestamp '2022-01-01' and timestamp '2022-10-01'	

Upgrading Jira Data Center

Perform a regular upgrade of the Jira Data Center cluster by following the steps from Upgrading Jira Data Center. 

What about reindexing?

During the upgrade procedure, you'll perform a reindex on the first node you’ve upgraded. Then, you’ll copy the index and the installation directory to the remaining nodes. This initial reindex will be much faster because it doesn’t include issues marked as archived. After the upgrade, you can open Jira to users so that they have access to issues that haven’t been archived and can create new issues.

Restoring the archived issues and reindexing again

After Jira Data Center is upgraded and functioning, you can restore the archived issues and reindex Jira again. You don’t need to close Jira for your users because reindexing will be performed on a single node.

1. Run a reverse SQL query to change the status of archived issues to “not archived”.
2. To perform the reindex, go to Administration () > System.
3. In the left-side panel, select Indexing
4. Select Full re-index and Re-index.

This reindex takes more time to complete but it doesn’t block your users from using Jira. Once the reindex is complete, the new index will be automatically distributed to the remaining nodes.

Overview

Every time a node goes offline and rejoins the cluster, it updates its index with recent operations, read directly from the database only while reindexing in the background. If a node has an index, the missing changes are still in the database due to a configurable retention period, and they make less than 10% of the whole index.

Let’s use a similar approach here. You’ll create an index by connecting a copy of your database for a fresh installation of Jira 9.4 to make the index compatible with the new version. This index will contain most of your data, and the nodes will apply the missing changes added to the original database when you start the upgrade.

After you upgrade the whole cluster, the nodes will detect the new index and add the missing changes instead of creating the whole index from scratch.

The only downtime for your users is the upgrade itself. Jira will be functional shortly after the upgrade.

The linked knowledge base article is a practical step-by-step instruction for handling the upgrade task and full reindex, while the following guide provides more theoretical details of downtime minimization. You can use both the article and the guide here to complete all the steps successfully and know the theory behind them.

Upgrading Jira Data Center

You can complete the following Step 1 and Step 2 without shutting down Jira Data Center.

Step 1: Creating the index outside the cluster

Make a copy of your database and connect Jira 9.4 to it. This will allow you to create an index compatible with your current Jira version outside your production cluster.

Copy the database

Make a copy of your live database. Don’t worry about users adding new data. You’ll switch back to the original database later on.

Complete this step as close to the actual upgrade as possible so that the difference between the original and cloned database isn’t too big and doesn’t exceed the retention period.

The maximum time of the retention period is two days by default. That’s how long information about recent operations is stored in the database, in the table ReplicatedIndexOperations. If you exceed this limit, the nodes won’t be able to add all missing changes from your original database because any changes older than two days will be deleted.

You can extend the retention period if you need more time. But if the changes exceed 10% of the whole index, the nodes will need a full reindex.

Connect the database copy to Jira 9.4

You’ll need a separate Jira 9.4 environment to which you’ll connect your database copy. Here are the requirements for this environment:

• Must be Jira 9.4.
• Must have the same apps as your production instance. apps can provide more data from custom fields and add this data to the index during reindexing.
• Must have a Data Center license. But you can use a single node.

To set up the environment:

1. Follow the Upgrade Jira on the first node instruction from Upgrading Jira Data Center. When configuring Jira 9.4, make sure to connect it to the copy of your database.
2. Follow the Post-upgrade steps on the first node instruction from Upgrading Jira Data Center. 

By following these steps, you will install a separate 9.4 instance, disable automatic reindex, and thus, give yourself time to install the apps or copy them from your production environment. When everything is ready, you can perform the reindex manually.

After the manual reindex is completed, you should have a Jira 9 index based on the information from the database copy. It’s still missing all the information added to the original database since you made the copy. But it'll be easier for your nodes to add missing entries for these changes than to create the whole index from scratch.

Step 2: Copying the index to your nodes

The Jira 9 index is stored in a different directory than the old one, so it won’t affect the existing cluster. You can already copy the new index to each node, so they don’t have to download it. Use the following directory: <local-home-directory>/caches/indexesV2

Step 3: Upgrading the first node

We recommend that you upgrade Jira Data Center by choosing a single node and upgrading it. After you start the first node, the database will be upgraded. As the next step, the node will detect the compatible index and only add entries for the missing changes. Other nodes will pick an index snapshot from the shared home.

This is the difference between the original database and cloned database that you used to create the Jira 9 index. From the node’s perspective, it looks like it was offline for a while.

To upgrade the node:

1. Stop the cluster.
2. Upgrade the first node. Follow the Upgrade Jira on the first node instruction from Upgrading Jira Data Center. When following the instruction, complete the last step and disable the reindex.
3. Complete post-upgrade steps on the first node. Follow the Post-upgrade steps on the first node instruction from Upgrading Jira Data Center. When following the instruction, skip rebuilding the index because you've already created the index outside the cluster.

Follow the guides to issue archiving and Jira reindexing outside the cluster. First, archive issues and proceed with the reindex.

To upgrade Jira apps:

1. Go to Administration () > Manage apps.

2. At the bottom of the page, select JIRA update check and look up the suggestions provided by your Universal Plugin Manager (UPM). Some apps have cross-platform compatibility and can be updated even before the upgrade. Update them in advance to speed up the upgrade process. 
   

   In Jira Data Center, some apps that you might previously install and upgrade via the UPM are now bundled with Jira and Jira Service Management.

   • AR4J (Advanced Roadmaps for Jira Software, formerly Jira Portfolio) is bundled since Jira 8.15.
   • A4J (Automation for Jira) is bundled since Jira 9.0.
   • Insights (now Assets) is bundled since Jira 8.15 (JSM 4.14).
3. Select a version you want to upgrade to and select Check.
4. Based on the app compatibility results described in the following table, take recommended actions.

To upgrade your applications:

1. Go to Administration () > Manage apps.
2. At the bottom of the page, select JIRA update check and look up the suggestions provided by your Universal Plugin Manager (UPM). Some apps have cross-platform compatibility and can be updated even before the upgrade. Update them in advance to speed up the upgrade process. 
3. Select a version you want to upgrade to and select Check.
4. Test the upgrading apps on your test environment first. So, you'll know which apps to upgrade or remove before you move to production.

Based on the app compatibility results described in the following table, take recommended actions.

In this case, we recommend removing all apps and installing only the compatible ones after the upgrade. 

First, get the list of apps for future reference. This list will help you determine which apps are compatible with the version you're upgrading to. To get the list:

1. Go to Administration > Manage apps.
2. At the bottom of the page, select JIRA update check.
3. Select a version you want to upgrade to and select Check.

Now, back up and delete the contents of the /plugin folder in Jira. This will delete all the apps you have. 

• For Server, go to <local-home-directory>/apps. 
• For Data Center, go to <shared-home-directory>/apps. 

After you've upgraded, install the compatible versions of your apps.