Skip to content

Upgrade PostgreSQL version

This guide explains how to upgrade PostgreSQL between minor or major versions.

Before you begin

  • Enable backups for your database first. See Restore RDS backup to find existing backups-
  • Upgrade development databases before production.
  • Choose your target version from the AWS documentation. Consider upgrading to PostgreSQL 16 first if going from 15 to 17.
  • Review database customizations outside Golden Path (such as read replicas).
  • Plan for downtime - major version upgrades cause service interruption.

What's new in PostgreSQL?

Check Amazon RDS for PostgreSQL updates

Step 1: Set target version

Create _gp_postgres_aurora_serverless_override.tf and set the engine version:

repo-iac/environments/dev/databases/_gp_postgres_aurora_serverless_override.tf
module "rds_aurora_serverless_main" {
  allow_major_version_upgrade = true   # Only needed for major version changes
  engine_version = "17.5"              # Replace with your target version
}

What happens if you set major version only?

AWS uses the default minor version, not necessarily the latest

Step 2: Set parameter group family

If you are changing the major version, update the parameter group family parameter in config_override.tf.

Find available values in the AWS documentation:

repo-iac/environments/dev/databases/config_override.tf
  db_cluster_parameter_group_family = "aurora-postgresql17"

Step 3: Apply changes

Plan, review, then apply the updated configuration

terraform plan
terraform apply

Track upgrade time

Time the upgrade to plan your production deployment. Production databases are larger and take longer to upgrade

Step 4: Verify upgrade

Test that your application works and that you can connect via ok forward.

Step 5: Reset variables

If in step 1 you created _gp_postgres_aurora_serverless_override.tf from scratch, delete the file.

If you updated it, remove the variables you added:

  • engine_version
  • allow_major_version_upgrade

Apply the changes:

terraform apply

Step 6: Commit changes

Commit and push all changes to your IaC repository.