feat: default params match tf aurora-cluster [INFRA-82505] (#137)

ahammond · github-actions[bot] · web-flow · commit b6f42d8c1311 · 2025-12-08T13:04:07.000-08:00
* feat: default params match tf aurora-cluster [INFRA-82505]

* chore: self mutation

Signed-off-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;

---------

Signed-off-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;
Co-authored-by: github-actions[bot] &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;
diff --git a/API.md b/API.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,154 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`@time-loop/cdk-aurora` is an opinionated AWS CDK construct library for deploying PostgreSQL Aurora clusters with best practices baked in. It provides a high-level abstraction that includes user management, secrets rotation, RDS Proxy, and database provisioning through custom CloudFormation resources.
+
+## Key Architecture Components
+
+### Main Construct (`src/aurora.ts`)
+The `Aurora` class is the primary construct that orchestrates:
+- **Aurora PostgreSQL Cluster**: Configured with encryption, CloudWatch logs, and performance insights
+- **Three User Types**: Manager (admin), Writer (DML), and Reader (read-only) with separate SecretsManager secrets
+- **RDS Proxy**: Optional proxy for connection pooling (default enabled, incompatible with multi-user rotation)
+- **Custom Provisioners**: Lambda-backed CloudFormation custom resources for database and user provisioning
+- **Activity Stream**: Optional database activity monitoring
+
+### Provisioning System
+Custom CloudFormation resources handle runtime database configuration:
+- **Database Provisioner** (`src/aurora.provision-database.ts`): Creates databases, schemas, and role grants
+- **User Provisioner** (`src/aurora.provision-user.ts`): Creates users, manages passwords, grants roles
+
+### Multi-User Rotation Pattern
+Uses AWS SecretsManager multi-user rotation with `_clone` users. **WARNING**: Fundamentally incompatible with RDS Proxy (see README.md proxy section). The proxy immediately blocks the old user when rotation occurs, defeating the "window of opportunity" pattern.
+
+## Common Commands
+
+### Build and Test
+```bash
+# Full build (compile + test + package)
+pnpm build
+
+# Compile TypeScript only
+pnpm compile
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Lint
+pnpm eslint
+```
+
+### Running Single Tests
+```bash
+# Run a specific test file
+pnpm test -- test/aurora.test.ts
+
+# Run tests matching a pattern
+pnpm test -- -t "provision-database"
+```
+
+### Projen Management
+This project uses Projen for project configuration. All changes should be made via `.projenrc.ts`:
+```bash
+# Regenerate project files from .projenrc.ts
+pnpm projen
+
+# Update dependencies
+pnpm upgrade
+```
+
+**Important**: Do NOT manually edit `package.json`, test configs, or other generated files. Edit `.projenrc.ts` and run `pnpm projen` instead.
+
+## Development Patterns
+
+### Testing
+- Tests use Jest with `sinon` for mocking
+- Database provisioner tests mock `pg` client connections
+- CDK snapshot tests verify synthesized CloudFormation templates
+- Test files mirror source structure: `test/aurora.*.test.ts` corresponds to `src/aurora.*.ts`
+
+### Lambda Bundling
+Lambda functions bundle external AWS SDK clients to avoid runtime issues:
+- `bundledDeps`: `@aws-sdk/client-rds`, `@aws-sdk/client-secrets-manager`, `aws-xray-sdk-core`, `pg`, `pg-format`
+- These are declared as `externalModules` in `bundling` config (paradoxically - this tells esbuild to bundle them)
+- Node modules like `pg` and `pg-format` use `nodeModules` in bundling config
+
+### Security Groups
+- Cluster and Proxy can have custom security groups via `securityGroups` and `proxySecurityGroups` props
+- Default behavior creates new security groups
+- Provisioning lambdas automatically get ingress rules to cluster
+
+### VPC Subnets
+- Default: `PRIVATE_WITH_EGRESS` subnets for cluster, proxy, and lambdas
+- Configurable via `vpcSubnets` prop
+- All components (cluster, proxy, provisioners) use same subnet selection
+
+## Parameter Groups and Parameters
+
+The construct supports two mutually exclusive approaches for cluster configuration:
+- `parameterGroup`: Pass an existing `IParameterGroup`
+- `parameters`: Pass a map of parameter key-value pairs (auto-creates parameter group)
+
+**Default parameters** (used when neither is specified):
+```typescript
+{
+  'rds.logical_replication': '1',
+  max_replication_slots: '10',
+  max_wal_senders: '10',
+  wal_sender_timeout: '0'
+}
+```
+
+## Important Gotchas
+
+1. **Proxy + Multi-User Rotation**: Do NOT use together. Set `skipAddRotationMultiUser: true` OR `skipProxy: true`.
+
+2. **Provisioning Dependencies**:
+   - User provisioning depends on database provisioning (roles must exist)
+   - User provisioning depends on proxy deployment (needs endpoint)
+   - Use `skipProvisionDatabase` and `skipUserProvisioning` for bootstrapping
+
+3. **Instance Count**: The `instances` prop is TOTAL count. The construct creates 1 writer + (instances - 1) readers.
+
+4. **Secret Naming**: Uses `multi-convention-namer` for consistent naming. Can prefix with `secretPrefix` for multiple clusters in same account.
+
+5. **Removal Policy**: The construct accepts `removalPolicy` prop but applies it differently across resources. Consider implementing the aspect pattern from `AURORA_DELETION_POLICY_IMPLEMENTATION.md` for comprehensive control.
+
+## Troubleshooting Database Issues
+
+See README.md "Troubleshooting" section for manual SQL commands to verify/fix:
+- Database connection privileges (`\l`, `GRANT CONNECT`)
+- Schema usage (`\dn+`, `GRANT USAGE`)
+- Default privileges (`\ddp`, `ALTER DEFAULT PRIVILEGES`)
+- Table privileges (`\dp`, `GRANT SELECT/INSERT/UPDATE/DELETE`)
+
+## Connection via JumpBox
+
+The README.md provides a complete script for connecting to Aurora through an SSM-enabled EC2 jump box. Key steps:
+1. Install AWS Session Manager plugin
+2. Configure SSH to use Session Manager as ProxyCommand
+3. Fetch SSH key from SecretsManager
+4. Create SSH tunnel to either cluster (manager) or proxy (reader/writer)
+5. Use `psql` through tunnel
+
+## File Structure
+
+```
+src/
+  aurora.ts                      # Main construct
+  aurora.provision-database.ts   # Database provisioner lambda
+  aurora.provision-user.ts       # User provisioner lambda
+  aurora.activity-stream.ts      # Activity stream custom resource
+  helpers.ts                     # Shared utilities
+  index.ts                       # Public exports
+test/
+  aurora.test.ts                 # Construct snapshot tests
+  aurora.provision-*.test.ts     # Provisioner unit tests
+  aurora.activity-stream.*.test.ts # Activity stream tests
+```
diff --git a/src/aurora.ts b/src/aurora.ts
@@ -268,16 +268,14 @@ export interface AuroraProps {
    * You can only specify parameterGroup or parameters but not both.
    * You need to use a versioned engine to auto-generate a DBClusterParameterGroup.
    *
-   * @default - defaultParameters
-   *
-   * const defaultParameters = {
-   *   // While these are mentioned in the docs, applying them doesn't work.
-   *   'rds.logical_replication': '1', // found in the cluster parameters.
-   *   // wal_level: 'logical', // not found in cluster parameters, but implicitly set by rds.logical_replication
-   *   max_replication_slots: '10', // Arbitrary, must be > 1
-   *   max_wal_senders: '10', // Arbitrary, must be > 1
-   *   wal_sender_timeout: '0', // Never time out. Risky, but recommended.
-   * };
+   * @default - defaults match tf aurora-cluster module, including:
+   * - Logical replication enabled (rds.logical_replication: '1')
+   * - SSL enforcement (rds.force_ssl: '1')
+   * - Query timeout protection (statement_timeout: 30s, idle_in_transaction: 5s)
+   * - Enhanced monitoring (log slow queries >200ms, lock waits, DDL statements)
+   * - Performance tuning (SSD-optimized costs, parallel workers, work_mem: 4MB)
+   * - Aggressive autovacuum (analyze_scale_factor: 0.01)
+   * - Extended replication slots (20) and wal senders (20)
    *
    */
   readonly parameters?: { [key: string]: string };
@@ -386,12 +384,47 @@ export class Aurora extends Construct {
       Maybe better to move it to a upstream library.
      */
     const defaultParameters = {
-      // While these are mentioned in the docs, applying them doesn't work.
-      'rds.logical_replication': '1', // found in the cluster parameters.
+      // Logical replication
+      'rds.logical_replication': '1',
       // wal_level: 'logical', // not found in cluster parameters, but implicitly set by rds.logical_replication
-      max_replication_slots: '10', // Arbitrary, must be > 1
-      max_wal_senders: '10', // Arbitrary, must be > 1
-      wal_sender_timeout: '0', // Never time out. Risky, but recommended.
+
+      // Replication configuration
+      max_replication_slots: '20',
+      max_wal_senders: '20',
+      max_logical_replication_workers: '8',
+
+      // Security
+      'rds.force_ssl': '1',
+
+      // Performance monitoring and logging
+      log_min_duration_statement: '200',
+      log_lock_waits: '1',
+      log_statement: 'ddl',
+      log_temp_files: '1024',
+      'pg_stat_statements.track': 'ALL',
+      'pg_stat_statements.track_utility': '0',
+      'pg_stat_statements.max': '5000',
+      track_io_timing: '1',
+      track_activity_query_size: '16384',
+      track_functions: 'all',
+
+      // Query timeout protection
+      statement_timeout: '30000',
+      idle_in_transaction_session_timeout: '5000',
+
+      // Performance tuning
+      random_page_cost: '1.1',
+      work_mem: '4096',
+      max_parallel_workers_per_gather: '4',
+      max_parallel_maintenance_workers: '4',
+      enable_partitionwise_aggregate: '0',
+
+      // Autovacuum tuning
+      autovacuum_analyze_scale_factor: '0.01',
+      autovacuum_freeze_max_age: '400000000',
+
+      // Date formatting
+      datestyle: 'ISO,YMD',
     };
     const parameters = props.parameterGroup || props.parameters ? props.parameters : defaultParameters;
 
diff --git a/test/aurora.test.ts b/test/aurora.test.ts
@@ -59,7 +59,11 @@ const createAurora = function (props?: AuroraProps) {
 describe('Aurora', () => {
   describe('default', () => {
     beforeAll(() => {
-      app = new App();
+      app = new App({
+        context: {
+          'aws:cdk:bundling-stacks': [], // Skip Lambda bundling in tests for performance
+        },
+      });
       stack = new Stack(app, 'test', { env: { region: 'us-west-2' } }); // We're using determineLatestNodeRuntime() which is region aware.
       kmsKey = new Key(stack, 'Key');
       vpc = new Vpc(stack, 'TestVpc', {
@@ -230,7 +234,11 @@ describe('Aurora', () => {
 
   describe('options', () => {
     beforeEach(() => {
-      app = new App();
+      app = new App({
+        context: {
+          'aws:cdk:bundling-stacks': [], // Skip Lambda bundling in tests for performance
+        },
+      });
       stack = new Stack(app, 'test', { env: { region: 'us-west-2' } }); // We're using determineLatestNodeRuntime() which is region aware.
       kmsKey = new Key(stack, 'Key');
       vpc = new Vpc(stack, 'TestVpc', {
