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 upgradesCheck 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
andrds_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
andrds_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
anddb_max_allocated_storage
attributes for your database, which are typically inresources/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
anddb_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