Skip to content

Upgrade PostgreSQL version

This guide explains how to upgrade PostgreSQL between major versions via Terraform, and how to maintain a correct Terraform configuration to avoid state drift when auto_minor_version_upgrade is set to true.

This guide takes into consideration an upgrade based on a standard distribution of PostgreSQL via the Golden Path PostgreSQL template (in this document referred to as

The guide below will do a upgrade from 13.11 to 15.3.

Before you begin

  • Familiarize yourself with the AWS PostgreSQL releases available and decide on upgrade version
  • Identify any major customizations done to that you need to consider (example: read-replica setup)
  • Plan a sequence for your upgrade: development environment first, then plan accordingly before upgrading a production database
  • Consider doing an incremental upgrade via PostgreSQL version 14 if you are going from 13 to 15
  • Make sure the backup retention period is set to a number greater than 0. Verify this by going to the AWS console > RDS > Databases > (your database) > Maintenance & backups > Backup > Automated backups. The default retention period in Golden Path when using is 1 day.

Step 1: Update configuration

Set the following variables in

  • engine_version = "15.3"

Engine version

If you don't specify the minor version you will get the current default version of PostgreSQL (not necessarily the latest).

  • allow_major_version_upgrade = true

Allow major version upgrade

Without this set to true you will not be able to upgrade between major versions.

Step 2: Apply changes

Plan, review, then apply the updated configuration

terraform plan
terraform apply

Upgrade time

Keep a note of how long time the actual upgrade takes. This will help in planning the production upgrade. Be aware that a production database can be larger than a development one, and as such can take longer to upgrade.

Step 3: Verify upgrade

Verify that your application is working as expected, and that you can connect via ok forward.

Step 4: Verify pre-upgrade snapshot of database

Go to RDS > Snapshots in the AWS console and identify the existence of a pre-upgrade snapshot.

The snapshot have the following naming convention:

  • preupgrade-{database-name}-{from-version}-to-{to-version}-{date}

If there are no snapshot, and you require one: ensure that backup_retention_period is set to 1 or higher.

Step 5: Reset variables

If auto_minor_version_upgrade is set to false, and you explicitly set engine_version to a minor version in, then this step is not applicable.

Set the following variables in

  • engine_version = null

Engine version

With auto_minor_version_upgrade set to true and engine_version is set to a major version, then AWS will choose the default minor version, which can be something different from the latest version you will get when AWS does automatic minor version upgrade.

  • allow_major_version_upgrade = false

Allow major version upgrade

It is good practice to set this to false to avoid any major version upgrade that can happen if someone sets (by mistake) a different major version in engine_version.

Step 6: Commit changes

Commit and push all changes to your IaC repository.