feat(rds): introduce type-safe engine versions (#9016)

Change engine versions, for boh cluster and instance engines,
from strings to strongly-typed classes with static constants representing common versions.

Fixes #6532

BREAKING CHANGE: the property 'version' has been changed from string to an engine-specific
  version class; use VersionClass.of() if you need to create a specific version of an engine from a string
* **rds**: the property ParameterGroupProps.family has been renamed to engine, and its type changed from string to IEngine
* **rds**: the property engineVersion in IClusterEngine changed from a string to EngineVersion
* **rds**: the property engineVersion in IInstanceEngine changed from a string to EngineVersion
* **rds**: the property parameterGroupFamily in IClusterEngine changed from required to optional
* **rds**: the property parameterGroupFamily in IInstanceEngine changed from required to optional

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

@@ -48,14 +48,14 @@ use the static factory methods on `DatabaseClusterEngine`:
 ```typescript
 new rds.DatabaseCluster(this, 'Database', {
   engine: rds.DatabaseClusterEngine.aurora({
-    version: '5.6.mysql_aurora.1.17.9',
+    version: rds.AuroraEngineVersion.VER_1_17_9, // different version class for each engine type
   },
   ...
 })
 ```
 
-See [the AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-database-instance.html#cfn-rds-dbinstance-engineversion)
-for a list of the supported versions for each engine type.
+If there isn't a constant for the exact version you want to use,
+all of the `Version` classes have a static `of` method that can be used to create an arbitrary version.
 
 By default, the master password will be generated and stored in AWS Secrets Manager with auto-generated description.
 
@@ -86,13 +86,16 @@ use the static factory methods on `DatabaseInstanceEngine`:
 
 ```typescript
 const instance = new rds.DatabaseInstance(this, 'Instance', {
-  engine: rds.DatabaseInstanceEngine.oracleSe1({
-    version: '19.0.0.0',
+  engine: rds.DatabaseInstanceEngine.oracleSe2({
+    version: rds.OracleEngineVersion.VER_19, // different version class for each engine type
   }),
   ...
 });
 ```
 
+If there isn't a constant for the exact version you want to use,
+all of the `Version` classes have a static `of` method that can be used to create an arbitrary version.
+
 To use the storage auto scaling option of RDS you can specify the maximum allocated storage.
 This is the upper limit to which RDS can automatically scale the storage. More info can be found
 [here](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PIOPS.StorageTypes.html#USER_PIOPS.Autoscaling)
@@ -173,24 +176,27 @@ instance.addRotationSingleUser(); // Will rotate automatically after 30 days
 [example of setting up master password rotation for a cluster](test/integ.cluster-rotation.lit.ts)
 
 The multi user rotation scheme is also available:
+
 ```ts
 instance.addRotationMultiUser('MyUser', {
-  secret: myImportedSecret // This secret must have the `masterarn` key
+  secret: myImportedSecret, // This secret must have the `masterarn` key
 });
 ```
 
 It's also possible to create user credentials together with the instance/cluster and add rotation:
+
 ```ts
 const myUserSecret = new rds.DatabaseSecret(this, 'MyUserSecret', {
-  username: 'myuser'
-  masterSecret: instance.secret
+  username: 'myuser',
+  masterSecret: instance.secret,
 });
 const myUserSecretAttached = myUserSecret.attach(instance); // Adds DB connections information in the secret
 
 instance.addRotationMultiUser('MyUser', { // Add rotation using the multi user scheme
-  secret: myUserSecretAttached
+  secret: myUserSecretAttached,
 });
 ```
+
 **Note**: This user must be created manually in the database using the master credentials.
 The rotation will start as soon as this user exists.
 

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

@@ -420,7 +420,7 @@ export class DatabaseCluster extends DatabaseClusterBase {
     const cluster = new CfnDBCluster(this, 'Resource', {
       // Basic
       engine: props.engine.engineType,
-      engineVersion: props.engine.engineVersion,
+      engineVersion: props.engine.engineVersion?.fullVersion,
       dbClusterIdentifier: props.clusterIdentifier,
       dbSubnetGroupName: subnetGroup.ref,
       vpcSecurityGroupIds: securityGroups.map(sg => sg.securityGroupId),
@@ -497,7 +497,7 @@ export class DatabaseCluster extends DatabaseClusterBase {
       const instance = new CfnDBInstance(this, `Instance${instanceIndex}`, {
         // Link to cluster
         engine: props.engine.engineType,
-        engineVersion: props.engine.engineVersion,
+        engineVersion: props.engine.engineVersion?.fullVersion,
         dbClusterIdentifier: cluster.ref,
         dbInstanceIdentifier: instanceIdentifier,
         // Instance properties

packages/@aws-cdk/aws-rds/lib/engine-version.ts

@@ -0,0 +1,23 @@
+/**
+ * A version of an engine -
+ * for either a cluster, or instance.
+ */
+export interface EngineVersion {
+  /**
+   * The full version string of the engine,
+   * for example, "5.6.mysql_aurora.1.22.1".
+   * It can be undefined,
+   * which means RDS should use whatever version it deems appropriate for the given engine type.
+   *
+   * @default - no version specified
+   */
+  readonly fullVersion?: string;
+
+  /**
+   * The major version of the engine,
+   * for example, "5.6".
+   * Used in specifying the ParameterGroup family
+   * and OptionGroup version for this engine.
+   */
+  readonly majorVersion: string;
+}

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

@@ -1,3 +1,5 @@
+import { EngineVersion } from './engine-version';
+
 /**
  * A common interface for database engines.
  * Don't implement this interface directly,
@@ -14,13 +16,16 @@ export interface IEngine {
    *
    * @default - use the default version for this engine type
    */
-  readonly engineVersion?: string;
+  readonly engineVersion?: EngineVersion;
 
   /**
    * The family to use for ParameterGroups using this engine.
    * This is usually equal to "<engineType><engineMajorVersion>",
    * but can sometimes be a variation of that.
    * You can pass this property when creating new ParameterGroup.
+   *
+   * @default - the ParameterGroup family is not known
+   *   (which means the major version of the engine is also not known)
    */
-  readonly parameterGroupFamily: string;
+  readonly parameterGroupFamily?: string;
 }

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

@@ -1,4 +1,5 @@
 export * from './engine';
+export * from './engine-version';
 export * from './cluster';
 export * from './cluster-ref';
 export * from './cluster-engine';