Upgrading a database version or changing the instance type

If you have a relational database 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, MariaDB, and MySQL to help you keep your database up to date.

Things to note before upgrading a database version or changing the instance type

A minor database version upgrade, a major database version upgrade, or changing your database 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.

It is not possible to go from a minor version e.g. 14.10 to major version 14, this causes a version mismatch when trying to apply.

Automatic minor engine version upgrades

AWS provide the ability to automatically upgrade your minor database version. This is enabled by default in the Cloud Platform, managed by the allow_minor_version_upgrade field within the cloud-platform-terraform-rds module.

It is important to understand the details of how AWS manage this. If you choose to allow AWS to manage automatic minor version upgrades, consider the following points:

AWS elect a ‘preferred’ (or target) minor version for each database engine. This is the version that AWS will upgrade to when you enable automatic minor version upgrades, assuming that your current version sits below this preferred version. This is also subject to change by AWS, and is not necessarily the latest minor version available for your database engine.
The automatic minor version upgrade schedule is determined by your RDS instance’s maintenance window. You can read more about maintenance windows in the AWS RDS documentation. This schedule can also be managed within the RDS module.

It is the user’s responsibility to understand and track automatic minor version management for RDS instances. A byproduct of using this feature is that your RDS terraform will not necessarily reflect the actual version of your database.

Determining your RDS instance’s target minor version

You can use the AWS CLI to discover the current AWS target minor version for automatic upgrades with the following command:

aws rds describe-db-engine-versions --output table --engine postgres --engine-version [your-current-version]

and referring to the AutoUpgrade column. For example, if you are currently on Postgres 14.3, you will see similar to the following output:

|||                      ValidUpgradeTarget
||+-------------+-----------------------+-----------+----------------+
||| AutoUpgrade |      Description      |  Engine   | EngineVersion  |
||+-------------+-----------------------+-----------+----------------+
|||  False      |  PostgreSQL 14.4-R1   |  postgres |  14.4          |
|||  False      |  PostgreSQL 14.5-R1   |  postgres |  14.5          |
|||  False      |  PostgreSQL 14.6-R1   |  postgres |  14.6          |
|||  True       |  PostgreSQL 14.7-R1   |  postgres |  14.7          |

Determining your RDS instance’s maintenance window

You can use the AWS CLI to discover the current maintenance window for your RDS instance with the following command:

aws rds describe-db-instances --output table --db-instance-identifier [your-db-instance-name] --query 'DBInstances[*].PreferredMaintenanceWindow'

Alternatively, you can view this information in the AWS console by navigating to your RDS instance and selecting the Maintenance & backups tab.

Manually upgrading to a new minor database version

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

To upgrade your minor database version, complete these three steps:

Raise and merge a PR to tell the apply pipeline to skip your namespace
Raise and merge a PR that updates the following attribute for your database, which is typically in resources/rds.tf in your namespace:
```
module "rds" {
  ...
  db_engine_version = "16.1" # the appropriate new minor version
  ...
}
```
As soon as this PR is merged, the upgrade will begin.
Raise and merge a PR to remove the APPLY_PIPELINE_SKIP_THIS_NAMESPACE added in step 1

Note on read replicas: If you have a read replica RDS instance associated with your primary instance, you will need to upgrade the minor version of the replica using the same steps as above in an initial PR, before proceeding with your primary instance upgrade.

Upgrade paths

You should refer to the end-of-life schedule for major and minor versions for PostgreSQL, MariaDB, Microsoft SQL Server, and MySQL to understand your upgrade paths. Typically, you will be able to upgrade to the latest minor version available on RDS.

Upgrading to a new major database version

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

Note: If you need to upgrade major versions more than once, e.g. from Postgres 12 to 14, and then 14 to 16, you must turn off prepare_for_major_upgrade (step 6) after each upgrade and then turn it back on (step 5). Otherwise, any upgrade after the first will fail.

To upgrade your major database version, complete these eight steps:

Find your current database version and instance type

In your namespace, find your database configuration and note the value for these four attributes:

module "rds" {
  ...
  db_engine         = "xyz"    # your database engine
  db_engine_version = "x.x.x"  # your current database engine version
  db_instance_class = "db.x.x" # your current database instance type
  rds_family        = "xyzx.x" # your current parameter group version
  ...
}

Understand your major version upgrade paths from your current db_engine_version by reading Upgrade paths for major version upgrades
Check if your current and new major database version supports the instance type you’re currently using by reading Supported DB engines for DB instance classes

If not, follow the Changing your database instance type guide first to change your instance class to one that is supported by your current and new major database version. You must change your instance type before attempting to upgrade, otherwise it will fail.

If you are unsure which instance type to choose, the Creating a relational database guide can help you choose what instance type to use based on your current version.
Raise and merge a PR to tell the apply pipeline to skip your namespace

Raise and merge a PR that updates the prepare_for_major_upgrade, db_engine, db_engine_version and rds_family attributes to your new major version:

module "rds" {
  ...
  prepare_for_major_upgrade = true
  db_engine                 = "postgres"
  db_engine_version         = "16.1"
  rds_family                = "postgres16"
  ...
}

Note: It is essential that you set prepare_for_major_upgrade to true. This will temporarily set your database’s parameter group to the RDS default, and prevent a failed apply during upgrade caused by clashing parameter group resources.

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

Once the major version upgrade has finished, raise and merge a PR that turns off the prepare_for_major_upgrade attribute that was turned on in step 5:
```
module "rds" {
  ...
  prepare_for_major_upgrade = false
  ...
}
```
If you have a read replica of your database, you will also need to update the db_engine_version and rds_family attributes to your new major version after the upgrade of your primary database has finished:
```
module "read_replica" {
  ...
  db_engine_version = "16.1"
  rds_family        = "postgres16"
  ...
}
```
Optionally, as the major upgrade already has downtime, it might be worthwhile changing your database instance type to the latest generation supported by your new major version
Raise and merge a PR to remove the APPLY_PIPELINE_SKIP_THIS_NAMESPACE file added in step 4

Upgrade paths

You should refer to the major version upgrade paths for PostgreSQL, MariaDB, Microsoft SQL Server, and MySQL to understand your upgrade paths from your current database engine version.

Changing your database instance type

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

To change your database instance type, complete these three steps:

Raise and merge a PR to tell the apply pipeline to skip your namespace
Raise and merge a PR that updates the db_instance_class and db_max_allocated_storage attributes for your database, which are typically in resources/rds.tf in your namespace:
```
module "rds" {
  ...
  db_instance_class        = "db.t4g.micro"
  db_max_allocated_storage = "500" # maximum storage for autoscaling
  ...
}
```
The Creating a relational database guide can help you decide which db_instance_class and db_max_allocated_storage values to use.

As soon as this PR is merged, the instance type change will begin.
Raise and merge a PR to remove the APPLY_PIPELINE_SKIP_THIS_NAMESPACE file added in step 1

This page was last reviewed on 30 August 2024. It needs to be reviewed again on 30 August 2025 by the page owner #cloud-platform .

This page was set to be reviewed before 30 August 2025 by the page owner #cloud-platform. This might mean the content is out of date.