Upgrading RDS Instance Major Version using Terraform or AWS CLI (PostgreSQL, MySQL, …)

When using Terraform to create RDS Instances and Clusters, the most common mistake is to create the Parameter Groups linked to them.

Doing that, when you try to major upgrade the RDS DB Version, your Terraform will not be able to proceed if you don’t apply it immediately, even if your lifecycle tells it to create before delete and all dependencies are fine.

The suggestion is for you create this “independency” even in the same recipe. But allow you to freely choose between parameter groups for different versions of that instance.

It is also a good practice to have one parameter profile per cluster/instance, since you may need to customize a specific one.

Now considering that you have that independent. Let’s go for the procedures!

In this explanation, we will simulate a RDS PostgreSQL Instance upgrade from 15.5 to 16.1

On Terraform:

• Ensure your aws_db_instance has “allow_major_version_upgrade = true“

• Ensure that the new Parameter Group has the correct family. In this case: postgres16

• Ensure your Terraform recipe will be able to apply this modification without deleting the old postgres15 Parameter Group

Now, on your recipe change the relevant parameters:

engine = "postgres"
engine_version = "16.1"
parameter_group_name = "rds-instance-xyz-postgres16-parameter-group"
allow_major_version_upgrade = true
apply_immediately = true # or false, depending of your need
maintenance_window = "your desired value in case you use apply_immediately = false"

Plan -> Check, then -> Apply your Terraform

If you chose to apply immediately, your instance will upgrade and automatically start using the new parameter group. If not

Applying the RDS planned/pending modifications immediately

If you didn’t choose to apply immediately by mistake, or if your maintenance window changed due to a Business need, don’t worry.

First, check if modifications are really queued to happen:

aws --profile <aws_profile> rds describe-db-instances --db-instance-identifier <db_instance_name> --region <region> --output json | jq '.DBInstances[].PendingModifiedValues'

{
"EngineVersion": "16.1"
}

If you prefer, you can also show all instance information on a table format and search for this section:

$ aws --profile <aws_profile> rds describe-db-instances --db-instance-identifier <db_instance_name> --region <region>
...

||+-------------------------------------------------+--------------------------------------------------------------------+||
|||                                                 PendingModifiedValues                                                |||
||+--------------------------------------------------------------------------------+-------------------------------------+||
|||  EngineVersion                                                                 |  16.1                               |||
||+--------------------------------------------------------------------------------+-------------------------------------+||

If the migration is correctly showing as pending, proceed with the immediately apply by executing the command bellow:

$ aws rds modify-db-instance --db-instance-identifier <db_instance_name> --apply-immediately --profile <aws_profile> --db-parameter-group-name "<new_parameter_group_name>"

I no longer want to Upgrade my RDS DB. How do I cancel a RDS pending modification before it happens?

Simply shutdown the instance, then turn it back on.

You should be able to see the PendingModifiedValues in a empty state {}

$ aws --profile <aws_profile> rds describe-db-instances --db-instance-identifier <db_instance_name> --region <region> --output json | jq '.DBInstances[].PendingModifiedValues'

The commands are very similar if you are dealing with Clusters. ex:

$ aws --profile <aws_profile> rds describe-db-clusters --db-cluster-identifier <db_cluster_name> --region <region> | jq '.DBClusters[].PendingModifiedValues'