@aws/nx-plugin-mcp 1.0.0-rc.32 → 1.0.0-rc.34

package/docs/snippets/connection/rdb-api-infrastructure.mdx

@@ -2,6 +2,7 @@
 title: RDB API Infrastructure
 ---
 import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
 
 To allow your API to connect to the database at runtime, the API Lambda functions must be deployed into the same VPC as the database and granted network and IAM access.
 
@@ -39,7 +40,7 @@ This example grants every handler in your API access, but if only some handlers
 </Fragment>
 <Fragment slot="terraform">
 
-Pass the database module outputs into your API module so it can reach the database and read its runtime configuration:
+Deploy the API into the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules:
 
 ```hcl title="packages/infra/src/main.tf"
 module "my_database" {
@@ -50,24 +51,44 @@ module "my_database" {
 }
 
 module "api" {
-  source             = "..."
-  enable_vpc         = true
-  vpc_id             = module.vpc.vpc_id
-  private_subnet_ids = module.vpc.private_subnet_ids
-
-  appconfig_application_id     = module.my_database.appconfig_application_id
-  database_cluster_resource_id = module.my_database.cluster_resource_id
-  database_runtime_user        = module.my_database.database_runtime_user
-  database_security_group_id   = module.my_database.security_group_id
-  database_port                = module.my_database.cluster_port
-
-  environment_variables = {
-    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
+  source     = "..."
+  enable_vpc = true
+  vpc_id     = module.vpc.vpc_id
+  subnet_ids = module.vpc.private_subnet_ids
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+
+  env = {
+    RUNTIME_CONFIG_APP_ID = module.runtime_config_appconfig.application_id
   }
 }
+
+resource "aws_vpc_security_group_ingress_rule" "api_to_database" {
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.api.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_to_database" {
+  security_group_id            = module.api.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
 ```
 
-Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. Ensure the API Lambda role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. `RUNTIME_CONFIG_APP_ID` should point at the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application, not an output of the database module.
 
 </Fragment>
 </Infrastructure>

package/docs/snippets/rdb/architecture.mdx

@@ -0,0 +1,38 @@
+---
+title: RDB Architecture
+---
+
+The deployed database has the following architecture. By default, an [Amazon RDS Proxy](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.html) sits in front of the Aurora cluster to pool connections and to enable [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) — see [Disable RDS Proxy](#disable-rds-proxy) for the alternative. The architecture is the same whether you select the PostgreSQL or MySQL engine; only the Aurora engine flavor differs.
+
+```d2 inline=true
+direction: right
+
+app: Application\n(Lambda, Agent, ...) {
+  shape: hexagon
+}
+
+proxy: RDS Proxy {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/rds.svg
+}
+
+migrations: Migrations Lambda {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+aurora: Aurora\n(PostgreSQL or MySQL) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/aurora.svg
+}
+
+secrets: Secrets Manager\n(DB credentials) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/secrets-manager.svg
+}
+
+app -> proxy: SQL (IAM auth)
+proxy -> aurora
+migrations -> aurora: Schema migrations
+migrations -> secrets: Admin credentials
+```

package/docs/snippets/rdb/cluster-instances.mdx

@@ -0,0 +1,31 @@
+---
+title: Cluster Instances
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Configure the writer and reader instances for your Aurora cluster.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  writer: ClusterInstance.serverlessV2('writer'),
+  readers: [ClusterInstance.serverlessV2('reader')],
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  instance_count = 2  # 1 writer + 1 reader
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/deletion-protection.mdx

@@ -0,0 +1,34 @@
+---
+title: Deletion Protection
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Deletion protection is enabled by default (`deletionProtection: true` in CDK, `deletion_protection = true` in Terraform) to protect the Aurora cluster from accidental deletion.
+
+#### Disable Deletion Protection
+
+You can disable deletion protection for environments where database deletion is expected, such as short-lived development or preview stacks.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  deletionProtection: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  deletion_protection = false
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/deploying.mdx

@@ -0,0 +1,107 @@
+---
+title: Deploying your Relational Database
+---
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+
+The relational database generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct is created in `common/constructs`. Example usage:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+    ...
+    const db = new MyDatabase(this, 'Db', {
+      vpc,
+      vpcSubnets: {
+        subnetType: SubnetType.PRIVATE_ISOLATED,
+      }
+    });
+  }
+}
+```
+
+This provisions an Aurora cluster with RDS Proxy, admin credentials, application database user, runtime config registration, and migration handler.
+
+The generated infrastructure creates two database users:
+- **Admin user** - Created during cluster provisioning with credentials stored in AWS Secrets Manager
+- **Application user** - Created via a Lambda custom resource with IAM authentication enabled and DML privileges (SELECT, INSERT, UPDATE, DELETE) on the application database
+</Fragment>
+<Fragment slot="terraform">
+The Terraform module is created in `common/terraform`. Example usage:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+
+  vpc_id              = module.vpc.vpc_id
+  database_subnet_ids = module.vpc.private_isolated_subnet_ids
+  lambda_subnet_ids   = module.vpc.private_subnet_ids
+
+  tags = local.common_tags
+}
+```
+
+This provisions an Aurora cluster with RDS Proxy, admin credentials, create-db-user Lambda, runtime config registration, migration Lambda, and container registry resources.
+
+The generated infrastructure creates two database users:
+- **Admin user** - Created during cluster provisioning with credentials stored in AWS Secrets Manager
+- **Application user** - Created via a Lambda function with IAM authentication enabled and DML privileges (SELECT, INSERT, UPDATE, DELETE) on the application database
+</Fragment>
+</Infrastructure>
+
+The application user is automatically created with a random name and IAM authentication. The generated database client is already configured to authenticate as this user using short-lived RDS tokens, so your application code never handles database passwords.
+
+Your VPC should include public subnets, private subnets with egress, and private isolated subnets. The database can run in private isolated subnets, while application Lambda functions should run in private subnets with egress so they can reach AWS services such as AppConfig.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+const vpc = new Vpc(this, 'Vpc', {
+  subnetConfiguration: [
+    {
+      name: 'public',
+      subnetType: SubnetType.PUBLIC,
+    },
+    {
+      name: 'private_with_egress',
+      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
+    },
+    {
+      name: 'private_isolated',
+      subnetType: SubnetType.PRIVATE_ISOLATED,
+    },
+  ],
+});
+```
+
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "~> 6.0"
+
+  name = "app"
+  ...
+  public_subnet_names  = ["public"]
+  private_subnet_names = ["private_with_egress"]
+  intra_subnet_names   = ["private_isolated"]
+
+  enable_nat_gateway = true
+  single_nat_gateway = true
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+Use the <Link path="guides/connection">`connection`</Link> generator to connect a project to this database — see the connection guide for the relevant compute type (e.g. FastAPI, MCP server, agent) for the infrastructure wiring required to reach it.

package/docs/snippets/rdb/encryption-key-rotation.mdx

@@ -0,0 +1,30 @@
+---
+title: Encryption Key Rotation
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The KMS key used to encrypt the Aurora cluster and its credentials secret has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableKeyRotation: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_key_rotation = false
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/engine-version.mdx

@@ -0,0 +1,63 @@
+---
+title: Engine Version
+---
+import Infrastructure from '@components/infrastructure.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Pin a specific Aurora engine version.
+
+By default, the generated local database container image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local container image version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
+
+The local database image is configured in the `localDev.image` field of the generated `config.json` file in your database project root. Update that value when you change engine versions.
+
+<OptionFilter when={{ engine: 'postgres' }}>
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  engineVersion: AuroraPostgresEngineVersion.VER_17_7,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  engine_version = "17.7"
+}
+```
+</Fragment>
+</Infrastructure>
+</OptionFilter>
+
+<OptionFilter when={{ engine: 'mysql' }}>
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  engineVersion: AuroraMysqlEngineVersion.VER_3_12_0,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  engine_version = "8.0.mysql_aurora.3.12.0"
+}
+```
+</Fragment>
+</Infrastructure>
+</OptionFilter>

package/docs/snippets/rdb/infrastructure.mdx

@@ -0,0 +1,35 @@
+---
+title: RDB Infrastructure
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src
+        - app
+          - dbs
+            - \<name>.ts Infrastructure specific to your database
+        - core
+          - rdb
+            - aurora.ts Generic Aurora database construct
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src
+        - app
+          - dbs
+            - \<name>
+              - \<name>.tf Module specific to your database
+        - core
+          - rdb
+            - aurora
+              - aurora.tf Generic Aurora module
+    </FileTree>
+  </Fragment>
+</Infrastructure>

package/docs/snippets/rdb/logging.mdx

@@ -0,0 +1,32 @@
+---
+title: Logging and Monitoring
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Performance Insights is enabled on the Aurora writer instance by default (encrypted with the cluster's KMS key). You can also export the Aurora engine logs to [CloudWatch Logs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_LogAccess.html) (`postgresql` for [Aurora PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.CloudWatch.html); `audit`, `error`, `general` and `slowquery` for [Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Integrating.CloudWatch.html)). Enable log export per database:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableCloudwatchLogs: true,
+  enablePerformanceInsights: false, // disable if not required
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_cloudwatch_logs      = true
+  enable_performance_insights = false # disable if not required
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/rds-proxy.mdx

@@ -0,0 +1,50 @@
+---
+title: RDS Proxy Configuration
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The generated infrastructure includes an [RDS Proxy](https://aws.amazon.com/rds/proxy/) by default, which sits between your application and the Aurora cluster. RDS Proxy provides several benefits:
+
+- **Connection pooling** - Maintains a pool of database connections that can be shared across application instances, reducing the overhead of establishing new connections
+- **Connection resilience** - Automatically handles failovers and reconnects during Aurora instance replacements or maintenance
+- **IAM authentication** - Supports IAM-based database authentication, eliminating the need to manage database credentials in your application code
+- **Improved security** - Enforces TLS encryption for all connections
+
+:::note[Additional Cost]
+RDS Proxy is enabled by default but incurs additional charges on top of the Aurora cluster cost. See [AWS RDS Proxy pricing](https://aws.amazon.com/rds/proxy/pricing/) for details. If you would prefer to disable the proxy, see the section below.
+:::
+
+#### Disable RDS Proxy
+
+You can disable the RDS proxy as follows:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableRdsProxy: false,
+});
+```
+
+When RDS Proxy is disabled, your application connects directly to the Aurora cluster endpoint.
+</Fragment>
+<Fragment slot="terraform">
+
+By default, RDS Proxy is enabled. You can disable it if needed:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_rds_proxy = false
+}
+```
+
+When RDS Proxy is disabled, your application connects directly to the Aurora cluster endpoint.
+</Fragment>
+</Infrastructure>
+

package/docs/snippets/rdb/removal-policy.mdx

@@ -0,0 +1,57 @@
+---
+title: Removal Policy
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The CDK construct retains the Aurora cluster by default (`removalPolicy: RemovalPolicy.RETAIN`). Change this when you want CDK stack deletion to snapshot or destroy the cluster instead.
+
+When using `RemovalPolicy.DESTROY`, deletion protection must also be disabled before the cluster can be deleted.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  removalPolicy: RemovalPolicy.SNAPSHOT,
+});
+```
+
+For an ephemeral environment where the database should be deleted with the stack:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  deletionProtection: false,
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+```
+
+::::caution[Data Loss]
+`RemovalPolicy.DESTROY` will permanently erase all data when the stack is deleted. Use only in ephemeral environments (such as automated tests). Use `RETAIN` or `SNAPSHOT` for all persistent and production stacks to prevent data loss.
+::::
+</Fragment>
+<Fragment slot="terraform">
+
+Terraform does not use CDK removal policies. By default, the module creates a final snapshot on deletion (`skip_final_snapshot = false`). To skip the final snapshot for an ephemeral environment:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  deletion_protection = false
+  skip_final_snapshot = true
+}
+```
+
+::::caution[Data Loss]
+`skip_final_snapshot = true` will permanently erase all data when the cluster is deleted. Use only in ephemeral environments (such as automated tests). Keep `skip_final_snapshot = false` for all persistent and production stacks to prevent data loss.
+::::
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/serverless-capacity.mdx

@@ -0,0 +1,32 @@
+---
+title: Serverless Capacity
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Control Aurora Serverless v2 scaling limits to match your workload.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  serverlessV2MinCapacity: 0.5,
+  serverlessV2MaxCapacity: 8,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  serverless_min_capacity = 0.5
+  serverless_max_capacity = 8
+}
+```
+</Fragment>
+</Infrastructure>

package/generators.json

@@ -448,6 +448,33 @@
       "description": "Connect a py#mcp-server to a py#dynamodb project",
       "metric": "g55",
       "hidden": true
+    },
+    "py#rdb": {
+      "factory": "./src/py/rdb/generator",
+      "schema": "./src/py/rdb/schema.json",
+      "description": "Create a Python relational database project",
+      "metric": "g56"
+    },
+    "py#rdb#fast-api-connection": {
+      "factory": "./src/py/rdb/fast-api-connection/generator",
+      "schema": "./src/py/rdb/fast-api-connection/schema.json",
+      "description": "Connect a py#fast-api project to a py#rdb project",
+      "metric": "g57",
+      "hidden": true
+    },
+    "py#rdb#agent-connection": {
+      "factory": "./src/py/rdb/agent-connection/generator",
+      "schema": "./src/py/rdb/agent-connection/schema.json",
+      "description": "Connect a py#agent to a py#rdb project",
+      "metric": "g58",
+      "hidden": true
+    },
+    "py#rdb#mcp-server-connection": {
+      "factory": "./src/py/rdb/mcp-server-connection/generator",
+      "schema": "./src/py/rdb/mcp-server-connection/schema.json",
+      "description": "Connect a py#mcp-server to a py#rdb project",
+      "metric": "g59",
+      "hidden": true
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.32",
+  "version": "1.0.0-rc.34",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/preset/schema.json

@@ -31,6 +31,12 @@
       "x-priority": "important",
       "x-prompt": "Which container engine would you like to use? (default: infer)"
     },
+    "module": {
+      "type": "string",
+      "description": "Module format for generated TypeScript code and configuration.",
+      "enum": ["esm", "cjs"],
+      "default": "esm"
+    },
     "preferInstallDependencies": {
       "type": "boolean",
       "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",