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.microwill take around 10 minutes.
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.tfin 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_NAMESPACEadded in step 1
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_versionby 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_versionandrds_familyattributes to your new major version:module "rds" { ... prepare_for_major_upgrade = true db_engine = "postgres" db_engine_version = "16.1" rds_family = "postgres16" ... }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_upgradeattribute 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_versionandrds_familyattributes 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_NAMESPACEfile 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_classanddb_max_allocated_storageattributes for your database, which are typically inresources/rds.tfin 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_classanddb_max_allocated_storagevalues 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_NAMESPACEfile added in step 1