chore: improve error messages and documentation for Database Insights configuration

Author: sakurai-ryo

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

@@ -1383,9 +1383,7 @@ The standard mode of Database Insights is enabled by default for Aurora database
 
 You can enhance the monitoring of your Aurora databases by enabling the advanced mode of Database Insights.
 
-See [AWS docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Database-Insights.html) for more information about Database Insights.
-
-The following example shows enabling the advanced mode of Database Insights for a clustered database.
+To control Database Insights mode, use the `databaseInsightsMode` property:
 
 ```ts
 declare const vpc: ec2.Vpc;
@@ -1401,11 +1399,9 @@ new rds.DatabaseCluster(this, 'Database', {
 });
 ```
 
-Note that settings regarding Database Insights are only possible at the cluster level.
-
-### Supported Engines
+Note: Database Insights are only supported for Amazon Aurora MySQL and Amazon Aurora PostgreSQL clusters.
 
-Database Insights supports Amazon Aurora MySQL and Amazon Aurora PostgreSQL.
+> Visit [CloudWatch Database Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Database-Insights.html) for more details.
 
 ## Enhanced Monitoring
 

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

@@ -428,8 +428,7 @@ interface DatabaseClusterBaseProps {
   /**
    * The amount of time, in days, to retain Performance Insights data.
    *
-   * @default - 7(PerformanceInsightRetention.DEFAULT) if `enablePerformanceInsights` is set,
-   * 465(PerformanceInsightRetention.MONTHS_15) if DatabaseInsightsMode.ADVANCED is set for `databaseInsightsMode`.
+   * @default - 7 days if `enablePerformanceInsights` is set. 465 days (15 months) if `databaseInsightsMode` is set to DatabaseInsightsMode.ADVANCED.
    */
   readonly performanceInsightRetention?: PerformanceInsightRetention;
 
@@ -443,7 +442,7 @@ interface DatabaseClusterBaseProps {
   /**
    * The database insights mode.
    *
-   * @default - DatabaseInsightsMode.STANDARD if Amazon Aurora engine is used, otherwise not set.
+   * @default - DatabaseInsightsMode.STANDARD when performance insights are enabled and Amazon Aurora engine is used, otherwise not set.
    */
   readonly databaseInsightsMode?: DatabaseInsightsMode;
 
@@ -556,8 +555,6 @@ export enum DatabaseInsightsMode {
 
   /**
    * Advanced mode.
-   *
-   * In advanced mode, Performance Insights must be enabled.
    */
   ADVANCED = 'advanced',
 }
@@ -865,13 +862,13 @@ abstract class DatabaseClusterNew extends DatabaseClusterBase {
       || props.performanceInsightEncryptionKey !== undefined
       || props.databaseInsightsMode === DatabaseInsightsMode.ADVANCED;
     if (enablePerformanceInsights && props.enablePerformanceInsights === false) {
-      throw new Error('`enablePerformanceInsights` disabled, but `performanceInsightRetention` or `performanceInsightEncryptionKey` was set, or `databaseInsightsMode` was set to `DatabaseInsightsMode.ADVANCED`');
+      throw new Error('`enablePerformanceInsights` disabled, but `performanceInsightRetention` or `performanceInsightEncryptionKey` was set, or `databaseInsightsMode` was set to \'${DatabaseInsightsMode.ADVANCED}\'');
     }
     if (props.databaseInsightsMode === DatabaseInsightsMode.ADVANCED
       && props.performanceInsightRetention
       && props.performanceInsightRetention !== PerformanceInsightRetention.MONTHS_15
     ) {
-      throw new Error('`performanceInsightRetention` must be set to PerformanceInsightRetention.MONTHS_15 when `databaseInsightsMode` is set to DatabaseInsightsMode.ADVANCED');
+      throw new Error('`performanceInsightRetention` must be set to \'${PerformanceInsightRetention.MONTHS_15}\' when `databaseInsightsMode` is set to \'${DatabaseInsightsMode.ADVANCED}\'');
     }
 
     // Database Insights is not supported for non-Aurora engines

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

@@ -2598,7 +2598,7 @@ describe('cluster', () => {
           enablePerformanceInsights: false,
           databaseInsightsMode: DatabaseInsightsMode.ADVANCED,
         });
-      }).toThrow(/`enablePerformanceInsights` disabled, but `performanceInsightRetention` or `performanceInsightEncryptionKey` was set, or `databaseInsightsMode` was set to `DatabaseInsightsMode.ADVANCED`/);
+      }).toThrow(/`enablePerformanceInsights` disabled, but `performanceInsightRetention` or `performanceInsightEncryptionKey` was set, or `databaseInsightsMode` was set to '\${DatabaseInsightsMode.ADVANCED}'/);
     });
 
     test('throw if the advanced mode of database insights is set and any retention other than MONTHS_15 is set for performanceInsightRetention', () => {
@@ -2614,7 +2614,7 @@ describe('cluster', () => {
           performanceInsightRetention: PerformanceInsightRetention.LONG_TERM,
           databaseInsightsMode: DatabaseInsightsMode.ADVANCED,
         });
-      }).toThrow(/`performanceInsightRetention` must be set to PerformanceInsightRetention.MONTHS_15 when `databaseInsightsMode` is set to DatabaseInsightsMode.ADVANCED/);
+      }).toThrow(/`performanceInsightRetention` must be set to '\${PerformanceInsightRetention.MONTHS_15}' when `databaseInsightsMode` is set to '\${DatabaseInsightsMode.ADVANCED}'/);
     });
   });