Upgrading an RDS database with a custom parameter group

[Drumar]

I have created a database cluster with CDK, created a PostgreSQL 15.4 cluster. I created a custom parametergroup like this (java)

IParameterGroup  pmGroup = new ParameterGroup(this, "rds-cluster-parameters-" + majorVersion, ParameterGroupProps.builder()
                    .description("Database Parameter Group for PostgreSQL " + majorVersion)
                    .engine(engine)
                    .parameters(Map.of("search_path", "\"$user\",public"))
                    .build());

DatabaseClusterProps databaseClusterProps = DatabaseClusterProps.builder()
                .engine(engine)
                .clusterIdentifier(name)
                .vpc(networkResources.getVpc())
                .vpcSubnets(subnetSelection)
                .securityGroups(sgGroups)
                .serverlessV2MaxCapacity(CONFIG.getAws().getStack().getRdsCluster().getScaling().maxUnits)
                .serverlessV2MinCapacity(CONFIG.getAws().getStack().getRdsCluster().getScaling().minUnits)
                .credentials(dbMasterSecret)
                .parameterGroup(pmGroup)
                .storageType(DBClusterStorageType.AURORA_IOPT1)
                .storageEncryptionKey(storageEncryptionKey)
                .deletionProtection(deleteProtection)
                .removalPolicy(removalPolicy)
                .defaultDatabaseName(CONFIG.getAws().getStack().getRdsCluster().getDefaultDatabaseName())
                .storageEncrypted(true)
                .iamAuthentication(false)
                .writer(ClusterInstance.serverlessV2("writer", ServerlessV2ClusterInstanceProps.builder()
                                .parameterGroup(pmGroup)
                                .autoMinorVersionUpgrade(true)
                                .allowMajorVersionUpgrade(false)
                                .build()))
               .readers(List.of()).build();
DatabaseCluster myCluster=new DatabaseCluster(this,"RDS Cluster", databaseClusterProps);

When I change the config to use version 16.1 instead deploying the stack throws an error:

Deployment failed: Error: The stack named AuroraRegionalServerlessClusterStack failed to deploy: UPDATE_ROLLBACK_COMPLETE: Resource handler returned message: "The current DB instance parameter group auroraregionalserverlessclusterstack-rdsclusterparameters15instanceparametergroup9b8f89a2-ohjwbiih2vzd is custom. You must explicitly specify a new DB instance parameter group, either default or custom, for the engine version upgrade. (Service: Rds, Status Code: 400, Request ID: 40c0e300-d69f-4b24-ab30-ce69da729cc3)" (RequestToken: 039ba251-9331-77e5-1086-3169ee9d5b12, HandlerErrorCode: InvalidRequest)

The question is: how can I realize a major version upgrade by updating the stack (configuration)? I tried to add a configuration item with a boolean to indicate a major version upgrade, and in that case create a new parameter group, but that does not seem to help me very much.

[urkle]

The process for upgrading a cluster with custom parameter groups is tricky and a multi-step process.

Step 1.

• Add the new parameter groups to your stack for the new engine version.

Note, you must keep the old ones, keep them attached to your cluster, and do not change the version on the cluster!

Step 2

• Run the stack to create the new (unused) parameter groups

Step 3

• Modify the stack again to bump the cluster engine version and switch to the newly created parameter groups (keep the old ones!)

Step 4

• Run the stack. This will perform the upgrade and swap out the parameter groups in the process

Step 5

Cleanup!..

• Remove the old parameter groups and run the stack to clear them out.

[Drumar]

Thanks! I had almost forgotten I had this question still ;-) But it is about to become more important shortly. Would be epic if we could do Blue/Green upgrades through CDK

[yudin-s]

For RDS major upgrades with custom parameter groups, the important part is that the parameter group family must match the target engine family.

I would not mutate the old parameter group in place. Create new target-version parameter groups first, then switch to them as part of the upgrade plan.

A safer sequence is:

1. Create new DB/cluster parameter groups for the target major version family.
2. Copy only parameters that are valid for the target family.
3. Test the upgrade on a restored snapshot.
4. In the upgrade deploy/window, change the engine version and attach the target-family parameter groups.
5. Reboot/apply pending changes intentionally.
6. Remove the old parameter groups only after the upgraded DB is stable.

The thing to avoid is a CDK diff that mixes “rewrite parameter group family”, “reattach parameter group”, and “upgrade engine” in a way CloudFormation cannot order safely.

In CDK I would model the target parameter group as a new resource with a stable id/name, not as a replacement of the old one. That makes the plan and rollback much easier to reason about.

[tamish-max]

For major RDS/Aurora upgrades with custom parameter groups, the safe path is a staged deploy, not an in-place family mutation.

What usually works reliably is:

1. create new parameter groups for the target engine family
2. deploy them unused
3. change the cluster engine version and switch the cluster/instance parameter groups in the same deploy
4. after the upgrade is stable, delete the old groups

In CDK terms, keep both old and new groups around temporarily:

var pg15Cluster = new ParameterGroup(...); // current family
var pg16Cluster = new ParameterGroup(...); // target family

var cluster = new DatabaseCluster(this, "Db", DatabaseClusterProps.builder()
    .engine(DatabaseClusterEngine.auroraPostgres(
        AuroraPostgresClusterEngineProps.builder()
            .version(AuroraPostgresEngineVersion.VER_16_1)
            .build()))
    .parameterGroup(pg16Cluster)
    .writer(ClusterInstance.serverlessV2("writer",
        ServerlessV2ClusterInstanceProps.builder()
            .parameterGroup(pg16Instance)
            .build()))
    .build());

Two gotchas:

• the parameter group family must match the target major version
• copy only parameters that are valid in the new family

I’d also test the exact sequence on a restored snapshot first, because “engine upgrade + custom parameter group swap” is where most surprises show up.