Upgrading a database version or changing the instance type

INFORMATION: Postgres 18 is now supported! Please see here for AWS guidance on major upgrade pathways

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.

Important for PostgreSQL databases with logical replication: If your database has rds.logical_replication enabled, check the RDS upgrade blockers troubleshooting guide before upgrading to avoid upgrade failures caused by logical replication slots or pglogical nodes.

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, raise and merge a PR that updates the following attribute for your database, which is typically in resources/rds.tf in your namespace:

```hcl
module "rds" {
  ...
  db_engine_version = "16.1" # the appropriate new minor version
  ...
}
```

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

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 for both the Primary and any Read Replica instance. 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.

Note: If your database has a read replica, read Upgrading a database with a read replica before you start.

To upgrade your major database version:

1. 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
     ...
   }
   

2. Understand your major version upgrade paths from your current db_engine_version by reading Upgrade paths for major version upgrades

3. 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.

4. For PostgreSQL, check your primary database for logical replication slots and pglogical nodes, and remove any you find

   AWS will not upgrade a database that has logical replication slots or pglogical nodes. It checks for them before it starts the upgrade, and if it finds any, your database stays on its current version. Commenting out or removing the logical replication parameters in your Terraform does not remove existing slots or nodes. You have to drop them with SQL.

   Follow Troubleshooting RDS upgrades with logical replication to check for and remove them. If another service, such as a reporting service, depends on them, agree the removal with the team that owns it first.

   Do not drop the physical replication slot that a read replica uses.

5. 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"
     ...
   }
   

   If you are upgrading your read replica together with the primary (option 1), update it in the same PR, including prepare_for_major_upgrade:

   module "read_replica" {
     ...
     prepare_for_major_upgrade = true
     db_engine_version         = "16.1"
     rds_family                = "postgres16"
     ...
   }
   

   Note: It is essential that you set prepare_for_major_upgrade to true on the primary and on any read replica. It temporarily moves each database to the RDS default parameter group, so that the apply does not fail on clashing parameter groups.

   As soon as this PR is merged, the major version upgrade will begin. If the apply fails, see If a major version upgrade fails.

6. 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. If you upgraded a read replica with the primary (option 1), turn it off on the read replica in the same PR:

   module "rds" {
     ...
     prepare_for_major_upgrade = false
     ...
   }
   
   module "read_replica" {
     ...
     prepare_for_major_upgrade = false
     ...
   }
   

   This moves your databases back to their custom parameter groups. Parameters that need a restart, such as rds.logical_replication or shared_preload_libraries, only take effect after you reboot the primary and any read replica.

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

Upgrading a database with a read replica

You cannot upgrade a read replica on its own. AWS upgrades in-region read replicas as part of the primary’s upgrade (AWS documentation). Choose one of these options:

Option 1: Upgrade the primary and read replica together

Follow the steps above, and set prepare_for_major_upgrade on the read replica as well as the primary in steps 5 and 6. The read replica is upgraded with the primary, and Terraform then updates its parameter group.

Option 2: Remove the read replica, upgrade the primary, then recreate the read replica

1. Raise a PR that removes the read_replica module, or sets its count to 0.
2. Upgrade the primary by following the steps above.
3. Raise a PR that adds the read replica back on the new version.

Your read replica is unavailable until it is recreated, and the new read replica gets a new identifier and endpoint, so you must update anything that connects to it.

If a major version upgrade fails

Error	Cause	What to do
DBParameterGroupAlreadyExists on the read replica	prepare_for_major_upgrade was not set on the read replica	Ask in #ask-cloud-platform. The Cloud Platform team needs to remove the clashing parameter group
Major Version Upgrade not supported for Postgres Read Replica DB Instances	The primary failed AWS’s pre-upgrade checks and stayed on its current version. This is usually caused by logical replication slots or pglogical nodes	Follow Troubleshooting RDS upgrades with logical replication
InvalidDBParameterGroupState when deleting a parameter group	The same as above, for a database without a read replica	Follow Troubleshooting RDS upgrades with logical replication

Do not cancel the apply pipeline build, or ask for its state lock to be removed, while an upgrade is in progress. A stopped build leaves the parameter groups out of step with your Terraform state. If a build fails, or your database stays upgrading for much longer than expected, ask in #ask-cloud-platform before you merge any other changes for that namespace.

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

```hcl
module "rds" {
  ...
  db_instance_class        = "db.t4g.micro"
  db_max_allocated_storage = "500" # maximum storage for autoscaling
  ...
}
```

The [Creating a relational database](/documentation/deploying-an-app/relational-databases/create.html#choosing-an-appropriate-instance-type) 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.

This page was last reviewed on 1 October 2026. It needs to be reviewed again on 1 October 2027 by the page owner #cloud-platform-notify .