# 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/restore-rds.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.

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

## Step 1: Set target version

Create `_gp_postgres_aurora_serverless_override.tf` and set the engine version:

```hcl title="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
}
```

<!-- prettier-ignore-start -->
!!! info "What happens if you set major version only?"
    AWS uses the default minor version, not necessarily the latest
<!-- prettier-ignore-end -->

## 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):

```hcl title="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

```shell
terraform plan
terraform apply
```

<!-- prettier-ignore-start -->
!!! tip "Track upgrade time"
    Time the upgrade to plan your production deployment. Production databases are larger and take longer to upgrade
<!-- prettier-ignore-end -->

## 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:

```shell
terraform apply
```

## Step 6: Commit changes

Commit and push all changes to your IaC repository.