Purpose

As of Jira 8.19, support for PostgreSQL 9.6 is removed. If you plan to upgrade to Jira 8.19 and your current database instance runs on PostgreSQL 9.6, we recommend that you upgrade your database to PostgreSQL 12 to avoid issues resulting from running Jira on an unsupported database platform.

For the full list of supported platforms, see Supported platforms.

Preparation

Use the native PostgreSQL database backup utilities to back up your current database cluster data in case you need to revert the upgrade. For more information, see PostgreSQL 9.6 Documentation — Chapter 25. Backup and Restore.

Resolution

Depending on the amount of data stored in your current database and the configuration of the database cluster, choose one of the following available methods to perform the upgrade:

Upgrade PostgreSQL 9.6 data files to PostgreSQL 12

This method uses the pg_upgrade utility to upgrade and reuse old PostgreSQL data files in the new database cluster. You can shorten the upgrade downtime by running pg_upgrade in link mode, which creates hard links instead of copying files to the new database cluster.

The following is a high-level outline of the upgrade process. For more detailed upgrade instructions, see PostgreSQL 12 Documentation — pg_upgrade.

1. Install PostgreSQL 12 and initialize the new database cluster.

2. Install any custom shared object files that were used by the old cluster and adjust authentication.

3. Stop Jira and both PostgreSQL servers.

4. Run pg_upgrade (add the the --link option to run pg_upgrade in link mode).

5. Perform a  VACUUM ANALYZE operation on the new database to regenerate optimizer statistics. Also consider running a database REINDEX.
   For more information, see PostgreSQL 12 documentation — ANALYZE and Optimize and Improve PostgreSQL Performance with VACUUM, ANALYZE, and REINDEX.

6. Start the PostgreSQL 12 server and — if required — perform post-upgrade processing.

7. Verify the upgrade by checking the pg_upgrade.log file and ensuring that Jira is working correctly.

8. If you’re satisfied with the upgrade, delete the old PostgreSQL 9.6 database cluster.

Use logical replication to upgrade to PostgreSQL 12 with minimal downtime

If you’re currently running PostgreSQL in a high-availability cluster configuration, you can use the native PostgreSQL replication tools or an external replication system to replicate data from your primary server to a new standby server running PostgreSQL 12. This method does not require taking Jira or your current database server offline to perform the the upgrade, which minimizes downtime to just a few seconds needed to perform a switchover.

For more information, see:

• PostgreSQL 12 Documentation — 18.6.3 Upgrading Data via Replication

• PostgreSQL 12 Documentation — Chapter 26. High Availability, Load Balancing, and Replication

Upgrade an Amazon RDS instance to PostgreSQL 12

If you’re running PostgreSQL 9.6 on an Amazon RDS instance, use this method to upgrade to PostgreSQL 12. Internally, Amazon RDS uses the pg_upgrade utility to perform the upgrade.

The following is a high-level outline of the upgrade process. For more detailed upgrade instructions, see Amazon Relational Database Service Documentation — Upgrading the PostgreSQL DB engine for Amazon RDS.

1. Create a snapshot of your current PostgreSQL database.

2. Start the upgrade from the AWS Management Console, the AWS CLI, or the RDS API as described in the RDS documentation.

3. Create a snapshot of the upgraded database.

4. Perform a  VACUUM ANALYZE operation on the new database to regenerate optimizer statistics. Also consider running a database REINDEX.
   For more information, see PostgreSQL 12 documentation — ANALYZE and Optimize and Improve PostgreSQL Performance with VACUUM, ANALYZE, and REINDEX.

5. If required, upgrade PostgreSQL extensions.

6. Verify the upgrade by checking the pg_upgrade_internal.log and pg_upgrade_server.log files and ensuring that Jira is working correctly.

Additional steps if you use our QuickStart templates

If your current Jira version supports PostgreSQL 12:

1. Scale your instance down to zero nodes.
2. Follow the steps above to manually upgrade the Postgres RDS instance from 9.6 to 12.
   Important note: don't change the DBEngineVersion parameter in the template, as this will result in a DBGroup error. 
3. Wait for the RDS upgrade to complete.
4. Scale your cluster up to 1 node first, check everything is working with no issues, then you can scale your cluster back up to the ideal number. 

If your current Jira version does not support PostgreSQL 12, you will also need to upgrade Jira after the RDS upgrade is complete (before scaling your cluster up to 1 node). Refer to the Normal upgrade section of Upgrading Jira Data Center on AWS for full details of how to upgrade.

Note that the DBEngineVersion parameter in the QuickStart template will continue to be set to version 9.6. If you try to change this parameter you will get a DBGroup error. As long as your application is connected to the new database version, there shouldn't be any problems.