> **Page index:** https://km.oslo.systems/llms.txt lists every page on this site, with a link to its Markdown version.

# 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](<https://km.oslo.systems/backup/restore-rds/index.md>) to find existing backups-
- Upgrade development databases before production.
- **Choose your target version** from the [AWS documentation](<https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.UpgradeVersion.html>). 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.

> [!NOTE]
>
> **What's new in PostgreSQL?**
>
> Check [Amazon RDS for PostgreSQL updates](<https://docs.aws.amazon.com/AmazonRDS/latest/PostgreSQLReleaseNotes/postgresql-versions.html>)

## 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
}
```

> [!NOTE]
>
> **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](<https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.setting-capacity.html#aurora-serverless-v2.parameter-groups-defaults>):

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
```

> [!TIP]
>
> **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.