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.

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 = "14.8" # 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

Upgrade paths

You should refer to the end-of-life schedule for major and minor versions for PostgreSQL, MariaDB, 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 11 to 14, and then 14 to 15, 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         = "14.8"
  rds_family                = "postgres14"
  ...
}

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 = "14" # you shouldn't include the minor version here
  rds_family        = "postgres14"
  ...
}
```
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, 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 23 July 2023. It needs to be reviewed again on 23 July 2024 by the page owner #cloud-platform .

This page was set to be reviewed before 23 July 2024 by the page owner #cloud-platform. This might mean the content is out of date.