Upgrading a database version of Aurora DB cluster

If you have an Aurora DB Cluster in the Cloud Platform, you must keep it up-to-date and use the most cost effective instance type for your needs.

AWS publishes an end-of-life schedule for major and minor versions of Postgresql and MySQL to help you keep your database up-to-date and plan for upgrades.

Things to note before upgrading a database version

A minor database version upgrade, a major database version upgrade, or changing your DB cluster instance type will always cause downtime.

There is no rule of thumb to work out how long it will take, but tests show an empty database using a db.t4g.micro will take around 10 minutes.

Upgrading to a new major database version

Note: This will cause downtime. See Things to note before upgrading your database.

When upgrading to a new major version of your Aurora DB Cluster, the steps depend on whether you are using a custom parameter group or not.

Case 1: Without a custom parameter group

If your Aurora DB cluster uses the default parameter group, follow these steps:

Check if your current and new major database version supports the instance type you’re currently using by reading Supported DB instance classes.

If your new major database version does not support your current instance type, update the instance type first before upgrading your major database version.
Raise and merge a PR to tell the apply pipeline to skip your namespace This is applicable for either updating the instance type or the major version of your database.

Raise and merge a PR that updates the allow_major_version_upgrade, engine_version attributes to your new major version:

module "rds_aurora" {
  source = "github.com/ministryofjustice/cloud-platform-terraform-rds-aurora?ref=<version>"

  # Database configuration
  engine         = "aurora-postgresql"
  engine_version = "15.5"
  allow_major_version_upgrade  = true

As soon as this PR is merged, the major version upgrade will begin.

Raise and merge a PR to remove the APPLY_PIPELINE_SKIP_THIS_NAMESPACE file added in step 2.

Case 2: With a custom parameter group

If your Aurora DB cluster uses the custom parameter group, follow these steps:

Check if your current and new major database version supports the instance type you’re currently using by reading Supported DB instance classes

If your new major database version does not support your current instance type, update the instance type first before upgrading your major database version.
Raise and merge a PR to tell the apply pipeline to skip your namespace This is applicable for either updating the instance type or the major version of your database.

Raise and merge a PR to switch temporarily to use the default parameter group for your current engine version.

For example, if you current DB engine is postgres14 set the db_parameter_group_name to default.aurora-postgresql14

module "rds_aurora" {
  source = "github.com/ministryofjustice/cloud-platform-terraform-rds-aurora?ref=<version>"

  # Database configuration
  engine         = "aurora-postgresql"
  engine_version = "14.6"
  db_parameter_group_name = "default.aurora-postgresql14"

Raise and merge a PR that updates the allow_major_version_upgrade, engine_version attributes to your new major version. You can remove the db_parameter_group_name in this step.
```
module "rds_aurora" {
  source = "github.com/ministryofjustice/cloud-platform-terraform-rds-aurora?ref=<version>"

  # Database configuration
  engine         = "aurora-postgresql"
  engine_version = "15.5"
  allow_major_version_upgrade  = true
```
Update your custom parameter group to match the new engine version family in the same PR.

For example, if your new major engine version is 15 then update the family to aurora-postgresql15.
```
  resource "aws_db_parameter_group" "rds_aurora_custom" {
     family = "aurora-postgresql15"

     parameter {
        name  = "log_error_verbosity"
        value = "TERSE"
     }
  }
```
Note:If you have lifecycle policy with create_before_destroy = true, you need to remove that in the same PR.

As soon as this PR is merged, the major version upgrade will begin.
After the upgrade is complete, raise and merge a PR to add back the db_parameter_group_name to the custom parameter group name and remove the APPLY_PIPELINE_SKIP_THIS_NAMESPACE file added in step 2.

This page was last reviewed on 15 September 2025. It needs to be reviewed again on 15 September 2026 by the page owner #cloud-platform .