feat(rds): simpler way to configure parameters for instance and cluster (#18126)

Fixes #18124


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: hoegertn

packages/@aws-cdk/aws-rds/README.md

@@ -527,6 +527,51 @@ new rds.OptionGroup(this, 'Options', {
 });
 ```
 
+## Parameter Groups
+
+Database parameters specify how the database is configured.
+For example, database parameters can specify the amount of resources, such as memory, to allocate to a database.
+You manage your database configuration by associating your DB instances with parameter groups.
+Amazon RDS defines parameter groups with default settings.
+
+You can create your own parameter group for your cluster or instance and associate it with your database:
+
+```ts
+declare const vpc: ec2.Vpc;
+
+const parameterGroup = new rds.ParameterGroup(this, 'ParameterGroup', {
+  engine: rds.DatabaseInstanceEngine.sqlServerEe({
+    version: rds.SqlServerEngineVersion.VER_11,
+  }),
+  parameters: {
+    locks: '100',
+  },
+});
+
+new rds.DatabaseInstance(this, 'Database', {
+  engine: rds.DatabaseInstanceEngine.SQL_SERVER_EE,
+  vpc,
+  parameterGroup,
+});
+```
+
+Another way to specify parameters is to use the inline field `parameters` that creates an RDS parameter group for you.
+You can use this if you do not want to reuse the parameter group instance for different instances:
+
+```ts
+declare const vpc: ec2.Vpc;
+
+new rds.DatabaseInstance(this, 'Database', {
+  engine: rds.DatabaseInstanceEngine.sqlServerEe({ version: rds.SqlServerEngineVersion.VER_11 }),
+  vpc,
+  parameters: {
+    locks: '100',
+  },
+});
+```
+
+You cannot specify a parameter map and a parameter group at the same time.
+
 ## Serverless
 
 [Amazon Aurora Serverless](https://aws.amazon.com/rds/aurora/serverless/) is an on-demand, auto-scaling configuration for Amazon

packages/@aws-cdk/aws-rds/lib/cluster.ts

@@ -10,7 +10,7 @@ import { Construct } from 'constructs';
 import { IClusterEngine } from './cluster-engine';
 import { DatabaseClusterAttributes, IDatabaseCluster } from './cluster-ref';
 import { Endpoint } from './endpoint';
-import { IParameterGroup } from './parameter-group';
+import { IParameterGroup, ParameterGroup } from './parameter-group';
 import { DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, renderCredentials, setupS3ImportExport, helperRemovalPolicy, renderUnless } from './private/util';
 import { BackupProps, Credentials, InstanceProps, PerformanceInsightRetention, RotationSingleUserOptions, RotationMultiUserOptions } from './props';
 import { DatabaseProxy, DatabaseProxyOptions, ProxyTarget } from './proxy';
@@ -116,6 +116,16 @@ interface DatabaseClusterBaseProps {
    */
   readonly parameterGroup?: IParameterGroup;
 
+  /**
+   * The parameters in the DBClusterParameterGroup to create automatically
+   *
+   * You can only specify parameterGroup or parameters but not both.
+   * You need to use a versioned engine to auto-generate a DBClusterParameterGroup.
+   *
+   * @default - None
+   */
+  readonly parameters?: { [key: string]: string };
+
   /**
    * The removal policy to apply when the cluster and its instances are removed
    * from the stack or replaced during an update.
@@ -338,11 +348,23 @@ abstract class DatabaseClusterNew extends DatabaseClusterBase {
     ];
 
     let { s3ImportRole, s3ExportRole } = setupS3ImportExport(this, props, /* combineRoles */ false);
+
+    if (props.parameterGroup && props.parameters) {
+      throw new Error('You cannot specify both parameterGroup and parameters');
+    }
+    const parameterGroup = props.parameterGroup ?? (
+      props.parameters
+        ? new ParameterGroup(this, 'ParameterGroup', {
+          engine: props.engine,
+          parameters: props.parameters,
+        })
+        : undefined
+    );
     // bind the engine to the Cluster
     const clusterEngineBindConfig = props.engine.bindToCluster(this, {
       s3ImportRole,
       s3ExportRole,
-      parameterGroup: props.parameterGroup,
+      parameterGroup,
     });
 
     const clusterAssociatedRoles: CfnDBCluster.DBClusterRoleProperty[] = [];
@@ -722,7 +744,21 @@ function createInstances(cluster: DatabaseClusterNew, props: DatabaseClusterBase
   }
 
   const instanceType = instanceProps.instanceType ?? ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MEDIUM);
-  const instanceParameterGroupConfig = instanceProps.parameterGroup?.bindToInstance({});
+
+  if (instanceProps.parameterGroup && instanceProps.parameters) {
+    throw new Error('You cannot specify both parameterGroup and parameters');
+  }
+
+  const instanceParameterGroup = instanceProps.parameterGroup ?? (
+    instanceProps.parameters
+      ? new ParameterGroup(cluster, 'InstanceParameterGroup', {
+        engine: props.engine,
+        parameters: instanceProps.parameters,
+      })
+      : undefined
+  );
+  const instanceParameterGroupConfig = instanceParameterGroup?.bindToInstance({});
+
   for (let i = 0; i < instanceCount; i++) {
     const instanceIndex = i + 1;
     const instanceIdentifier = props.instanceIdentifierBase != null ? `${props.instanceIdentifierBase}${instanceIndex}` :

packages/@aws-cdk/aws-rds/lib/instance.ts

@@ -12,7 +12,7 @@ import { DatabaseSecret } from './database-secret';
 import { Endpoint } from './endpoint';
 import { IInstanceEngine } from './instance-engine';
 import { IOptionGroup } from './option-group';
-import { IParameterGroup } from './parameter-group';
+import { IParameterGroup, ParameterGroup } from './parameter-group';
 import { DEFAULT_PASSWORD_EXCLUDE_CHARS, defaultDeletionProtection, engineDescription, renderCredentials, setupS3ImportExport, helperRemovalPolicy, renderUnless } from './private/util';
 import { Credentials, PerformanceInsightRetention, RotationMultiUserOptions, RotationSingleUserOptions, SnapshotCredentials } from './props';
 import { DatabaseProxy, DatabaseProxyOptions, ProxyTarget } from './proxy';
@@ -822,6 +822,16 @@ export interface DatabaseInstanceSourceProps extends DatabaseInstanceNewProps {
    * @default - no name
    */
   readonly databaseName?: string;
+
+  /**
+   * The parameters in the DBParameterGroup to create automatically
+   *
+   * You can only specify parameterGroup or parameters but not both.
+   * You need to use a versioned engine to auto-generate a DBParameterGroup.
+   *
+   * @default - None
+   */
+  readonly parameters?: { [key: string]: string };
 }
 
 /**
@@ -877,6 +887,17 @@ abstract class DatabaseInstanceSource extends DatabaseInstanceNew implements IDa
 
     this.instanceType = props.instanceType ?? ec2.InstanceType.of(ec2.InstanceClass.M5, ec2.InstanceSize.LARGE);
 
+    if (props.parameterGroup && props.parameters) {
+      throw new Error('You cannot specify both parameterGroup and parameters');
+    }
+
+    const dbParameterGroupName = props.parameters
+      ? new ParameterGroup(this, 'ParameterGroup', {
+        engine: props.engine,
+        parameters: props.parameters,
+      }).bindToInstance({}).parameterGroupName
+      : this.newCfnProps.dbParameterGroupName;
+
     this.sourceCfnProps = {
       ...this.newCfnProps,
       associatedRoles: instanceAssociatedRoles.length > 0 ? instanceAssociatedRoles : undefined,
@@ -888,6 +909,7 @@ abstract class DatabaseInstanceSource extends DatabaseInstanceNew implements IDa
       engineVersion: props.engine.engineVersion?.fullVersion,
       licenseModel: props.licenseModel,
       timezone: props.timezone,
+      dbParameterGroupName,
     };
   }
 

packages/@aws-cdk/aws-rds/lib/props.ts

@@ -43,6 +43,16 @@ export interface InstanceProps {
    */
   readonly parameterGroup?: IParameterGroup;
 
+  /**
+   * The parameters in the DBParameterGroup to create automatically
+   *
+   * You can only specify parameterGroup or parameters but not both.
+   * You need to use a versioned engine to auto-generate a DBParameterGroup.
+   *
+   * @default - None
+   */
+  readonly parameters?: { [key: string]: string };
+
   /**
    * Whether to enable Performance Insights for the DB instance.
    *

packages/@aws-cdk/aws-rds/test/cluster.test.ts

@@ -10,6 +10,7 @@ import * as cxapi from '@aws-cdk/cx-api';
 import {
   AuroraEngineVersion, AuroraMysqlEngineVersion, AuroraPostgresEngineVersion, CfnDBCluster, Credentials, DatabaseCluster,
   DatabaseClusterEngine, DatabaseClusterFromSnapshot, ParameterGroup, PerformanceInsightRetention, SubnetGroup, DatabaseSecret,
+  DatabaseInstanceEngine, SqlServerEngineVersion,
 } from '../lib';
 
 describe('cluster', () => {
@@ -322,6 +323,112 @@ describe('cluster', () => {
     });
   });
 
+  test('cluster with inline parameter group', () => {
+    // GIVEN
+    const stack = testStack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+
+    // WHEN
+    new DatabaseCluster(stack, 'Database', {
+      engine: DatabaseClusterEngine.AURORA,
+      parameters: {
+        locks: '100',
+      },
+      instanceProps: {
+        vpc,
+        parameters: {
+          locks: '200',
+        },
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBCluster', {
+      DBClusterParameterGroupName: {
+        Ref: 'DatabaseParameterGroup2A921026',
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBClusterParameterGroup', {
+      Family: 'aurora5.6',
+      Parameters: {
+        locks: '100',
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBInstance', {
+      DBParameterGroupName: {
+        Ref: 'DatabaseInstanceParameterGroup6968C5BF',
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBParameterGroup', {
+      Family: 'aurora5.6',
+      Parameters: {
+        locks: '200',
+      },
+    });
+  });
+
+  test('cluster with inline parameter group and parameterGroup arg fails', () => {
+    // GIVEN
+    const stack = testStack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const parameterGroup = new ParameterGroup(stack, 'ParameterGroup', {
+      engine: DatabaseInstanceEngine.sqlServerEe({
+        version: SqlServerEngineVersion.VER_11,
+      }),
+      parameters: {
+        locks: '50',
+      },
+    });
+
+    expect(() => {
+      new DatabaseCluster(stack, 'Database', {
+        engine: DatabaseClusterEngine.AURORA,
+        parameters: {
+          locks: '100',
+        },
+        parameterGroup,
+        instanceProps: {
+          vpc,
+          parameters: {
+            locks: '200',
+          },
+        },
+      });
+    }).toThrow(/You cannot specify both parameterGroup and parameters/);
+  });
+
+  test('instance with inline parameter group and parameterGroup arg fails', () => {
+    // GIVEN
+    const stack = testStack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const parameterGroup = new ParameterGroup(stack, 'ParameterGroup', {
+      engine: DatabaseInstanceEngine.sqlServerEe({
+        version: SqlServerEngineVersion.VER_11,
+      }),
+      parameters: {
+        locks: '50',
+      },
+    });
+
+    expect(() => {
+      new DatabaseCluster(stack, 'Database', {
+        engine: DatabaseClusterEngine.AURORA,
+        parameters: {
+          locks: '100',
+        },
+        instanceProps: {
+          vpc,
+          parameterGroup,
+          parameters: {
+            locks: '200',
+          },
+        },
+      });
+    }).toThrow(/You cannot specify both parameterGroup and parameters/);
+  });
+
   describe('performance insights', () => {
     test('cluster with all performance insights properties', () => {
       // GIVEN

packages/@aws-cdk/aws-rds/test/instance.test.ts

@@ -246,6 +246,52 @@ describe('instance', () => {
     });
   });
 
+  test('instance with inline parameter group', () => {
+    // WHEN
+    new rds.DatabaseInstance(stack, 'Database', {
+      engine: rds.DatabaseInstanceEngine.sqlServerEe({ version: rds.SqlServerEngineVersion.VER_11 }),
+      vpc,
+      parameters: {
+        locks: '100',
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBInstance', {
+      DBParameterGroupName: {
+        Ref: 'DatabaseParameterGroup2A921026',
+      },
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::RDS::DBParameterGroup', {
+      Family: 'sqlserver-ee-11.0',
+      Parameters: {
+        locks: '100',
+      },
+    });
+  });
+
+  test('instance with inline parameter group and parameterGroup arg fails', () => {
+    const parameterGroup = new rds.ParameterGroup(stack, 'ParameterGroup', {
+      engine: rds.DatabaseInstanceEngine.sqlServerEe({
+        version: rds.SqlServerEngineVersion.VER_11,
+      }),
+      parameters: {
+        key: 'value',
+      },
+    });
+
+    expect(() => {
+      new rds.DatabaseInstance(stack, 'Database', {
+        engine: rds.DatabaseInstanceEngine.sqlServerEe({ version: rds.SqlServerEngineVersion.VER_11 }),
+        vpc,
+        parameters: {
+          locks: '100',
+        },
+        parameterGroup,
+      });
+    }).toThrow(/You cannot specify both parameterGroup and parameters/);
+  });
+
   test('can specify subnet type', () => {
     new rds.DatabaseInstance(stack, 'Instance', {
       engine: rds.DatabaseInstanceEngine.mysql({