cdk-rds-sql 7.0.2 → 7.1.0

package/.pre-commit-config.yaml

@@ -35,6 +35,7 @@ repos:
         language: system
         entry: sh -c 'npx tsc --noEmit'
         files: \.ts$
+        pass_filenames: false
   - repo: local
     hooks:
       - id: synth
@@ -42,6 +43,7 @@ repos:
         language: system
         entry: sh -c 'npx cdk synth --quiet --context vpc-id=$VPC_ID'
         files: src/.*\.ts$
+        pass_filenames: false
   - repo: local
     hooks:
       - id: compile-project
@@ -50,6 +52,7 @@ repos:
         language: system
         entry: sh -c 'npx projen compile'
         files: \.ts$
+        pass_filenames: false
   - repo: local
     hooks:
       - id: test
@@ -58,3 +61,4 @@ repos:
         language: system
         entry: sh -c 'npx jest --coverage=false'
         files: \.ts$
+        pass_filenames: false

package/.prettierignore

@@ -10,3 +10,9 @@ tsconfig.json
 .projen/
 .eslintrc.json
 API.md
+cdk.out
+.claude/
+lib/
+cdk.context.json
+src/handler/handler.js
+tsconfig.dev.json

package/README.md

@@ -1,8 +1,9 @@
 # About
 
 This CDK construct library makes it possible to create databases,
-schemas, and roles in an Aurora Serverless v2, RDS Database Cluster or
-Database Instance. Both PostgreSQL and MySQL databases are supported.
+schemas, and roles in an Aurora Serverless v2, RDS Database Cluster,
+Database Instance, or AWS DSQL clusters. PostgreSQL, MySQL, and DSQL
+databases are supported.
 
 This construct library is intended to be used in enterprise
 environments, and works in isolated subnets.
@@ -103,20 +104,6 @@ const provider = new Provider(this, "Provider", {
 })
 ```
 
-### Disabling SSL
-
-The default connection to RDS is ssl enabled. You can disable ssl by
-setting the `ssl` option to `false`:
-
-```ts
-const provider = new Provider(this, "Provider", {
-  vpc: vpc,
-  instance: instance,
-  secret: cluster.secret!,
-  ssl: false, // default is true
-})
-```
-
 ## Roles
 
 Create a postgres role (or mysql user) for a cluster as follows:
@@ -388,6 +375,92 @@ initialPolicy: [
 
 Note that your VPC will need an SSM Parameters interface endpoint to support this.
 
+# AWS DSQL Support
+
+This construct also supports AWS DSQL. DSQL is a great number of
+limitations around it's postgresql support, so there is some learing
+curve. This library supports creating roles, schemas, and executing
+SQL on DSQL clusters. Creating databases is not supported by DSQL.
+
+## DSQL Provider Setup
+
+DSQL clusters don't require a VPC or secrets since they use IAM authentication:
+
+```ts
+import * as dsql from "aws-cdk-lib/aws-dsql"
+import { Provider } from "cdk-rds-sql"
+
+const dsqlCluster = new dsql.CfnCluster(this, "DsqlCluster", {
+  deletionProtectionEnabled: false,
+})
+
+const provider = new Provider(this, "Provider", {
+  cluster: dsqlCluster,
+  // No VPC or secret needed for DSQL
+})
+```
+
+You can access DSQL from within a VPC, but cdk-rds-sql has not been
+specifically tested with that scenario.
+
+## DSQL Roles
+
+DSQL always uses IAM authentication, so the `enableIamAuth` property is ignored:
+
+```ts
+import { Role } from "cdk-rds-sql"
+
+const role = new Role(this, "Role", {
+  provider: provider,
+  roleName: "myrole",
+})
+```
+
+## Using DSQL
+
+Connecting to DSQL requires a couple of things:
+
+1. Your IAM role needs the `dsql:DbConnect` IAM permission to connect to the cluster.
+2. You probably want a normal postgres role (not "admin") to use from your apps.
+3. Your IAM role needs to be connected to your postgres role: use the `IamGrant` construct for that:
+
+   ```ts
+   new IamGrant(this, "LambdaIamGrant", {
+     provider: provider,
+     roleName: role.roleName,
+     resourceArn: queryLambda.role!.roleArn,
+   })
+   ```
+
+4. From your code use the Dsql signer to create the password:
+
+   ```ts
+   import { DsqlSigner } from "@aws-sdk/dsql-signer"
+   import { Client } from "pg"
+
+   const region =
+     process.env["AWS_REGION"] || process.env["AWS_DEFAULT_REGION"] || "us-west-2"
+
+   // Generate DSQL auth token using AWS SDK
+   const signer = new DsqlSigner({
+     hostname: host,
+     region,
+   })
+
+   const authToken = await signer.getDbConnectAuthToken()
+
+   const client = new Client({
+     host,
+     port: 5432,
+     user: dbUser,
+     database: dbName,
+     password: authToken,
+     ssl: { rejectUnauthorized: false },
+   })
+
+   await client.connect()
+   ```
+
 # IPv6
 
 If you use the provider in an IPv6 subnet you probably need these settings:
@@ -404,6 +477,20 @@ const provider = new Provider(this, "Provider", {
 }
 ```
 
+# Disabling SSL
+
+The default connection to RDS is ssl enabled. You can disable ssl by
+setting the `ssl` option to `false`:
+
+```ts
+const provider = new Provider(this, "Provider", {
+  vpc: vpc,
+  instance: instance,
+  secret: cluster.secret!,
+  ssl: false, // default is true
+})
+```
+
 # Working on this code
 
 This code is managed by
@@ -432,6 +519,10 @@ If you want to use an existing vpc:
 
     npx cdk deploy --context vpc-id=vpc-0123456789 TestServerlessV2Stack
 
+You can also test DSQL support with:
+
+    npx projen integ:deploy:dsql
+
 # To do
 
 - Update role: will not revoke connect to previous database if database name has changed.

package/lambda/engine.abstract.ts

@@ -8,6 +8,7 @@ import {
   EngineRoleProperties,
   EngineSchemaProperties,
   EngineSqlProperties,
+  EngineIamGrantProperties,
 } from "./types"
 
 export interface EngineConnectionConfig {
@@ -74,6 +75,21 @@ export abstract class AbstractEngine {
   ): string | string[]
   abstract deleteSql(resourceId: string, props: EngineSqlProperties): string | string[]
 
+  abstract createIamGrant(
+    resourceId: string,
+    props: EngineIamGrantProperties
+  ): string | string[]
+  abstract updateIamGrant(
+    resourceId: string,
+    oldResourceId: string,
+    props: EngineIamGrantProperties,
+    oldProps: EngineIamGrantProperties
+  ): string | string[]
+  abstract deleteIamGrant(
+    resourceId: string,
+    props: EngineIamGrantProperties
+  ): string | string[]
+
   abstract executeSQL(
     sql: string | string[],
     config: EngineConnectionConfig

package/lambda/engine.dsql.ts

@@ -0,0 +1,302 @@
+import { DsqlSigner } from "@aws-sdk/dsql-signer"
+import { format as pgFormat } from "node-pg-format"
+import { Client, ClientConfig } from "pg"
+import { AbstractEngine, EngineConnectionConfig } from "./engine.abstract"
+import {
+  EngineDatabaseProperties,
+  EngineRoleProperties,
+  EngineSchemaProperties,
+  EngineSqlProperties,
+  EngineIamGrantProperties,
+} from "./types"
+
+export class DsqlEngine extends AbstractEngine {
+  createDatabase(
+    _resourceId: string,
+    _props: EngineDatabaseProperties
+  ): string | string[] {
+    throw new Error(
+      "DSQL does not support creating databases. Database is always 'postgres'."
+    )
+  }
+
+  updateDatabase(
+    _resourceId: string,
+    _oldResourceId: string,
+    _props: EngineDatabaseProperties
+  ): string[] {
+    throw new Error(
+      "DSQL does not support database operations. Database is always 'postgres'."
+    )
+  }
+
+  deleteDatabase(_resourceId: string, _masterUser: string): string | string[] {
+    throw new Error(
+      "DSQL does not support deleting databases. Database is always 'postgres'."
+    )
+  }
+
+  async createRole(resourceId: string, props: EngineRoleProperties): Promise<string[]> {
+    const sql = ["BEGIN"]
+
+    // DSQL always uses IAM authentication, no passwords
+    sql.push(pgFormat("CREATE ROLE %I WITH LOGIN", resourceId))
+
+    if (props?.DatabaseName) {
+      sql.push(
+        pgFormat("GRANT CONNECT ON DATABASE %I TO %I", props.DatabaseName, resourceId)
+      )
+    }
+
+    sql.push("COMMIT")
+    return sql
+  }
+
+  async updateRole(
+    resourceId: string,
+    oldResourceId: string,
+    props: EngineRoleProperties,
+    oldProps: EngineRoleProperties
+  ): Promise<string[]> {
+    const sql = ["BEGIN"]
+
+    if (oldResourceId !== resourceId) {
+      sql.push(pgFormat("ALTER ROLE %I RENAME TO %I", oldResourceId, resourceId))
+    }
+
+    // Handle database permission changes
+    if (
+      oldProps?.DatabaseName &&
+      props?.DatabaseName &&
+      oldProps.DatabaseName !== props.DatabaseName
+    ) {
+      // Revoke from old database and grant to new
+      sql.push(
+        pgFormat(
+          "REVOKE CONNECT ON DATABASE %I FROM %I",
+          oldProps.DatabaseName,
+          resourceId
+        )
+      )
+      sql.push(
+        pgFormat("GRANT CONNECT ON DATABASE %I TO %I", props.DatabaseName, resourceId)
+      )
+    } else if (props?.DatabaseName && !oldProps?.DatabaseName) {
+      // Grant to new database
+      sql.push(
+        pgFormat("GRANT CONNECT ON DATABASE %I TO %I", props.DatabaseName, resourceId)
+      )
+    } else if (!props?.DatabaseName && oldProps?.DatabaseName) {
+      // Revoke from old database
+      sql.push(
+        pgFormat(
+          "REVOKE CONNECT ON DATABASE %I FROM %I",
+          oldProps.DatabaseName,
+          resourceId
+        )
+      )
+    }
+
+    sql.push("COMMIT")
+    return sql
+  }
+
+  deleteRole(resourceId: string, props: EngineRoleProperties): string | string[] {
+    const sql = ["BEGIN"]
+
+    if (props?.DatabaseName) {
+      sql.push(
+        pgFormat(
+          "REVOKE ALL PRIVILEGES ON DATABASE %I FROM %I",
+          props.DatabaseName,
+          resourceId
+        )
+      )
+    }
+
+    sql.push(pgFormat("DROP ROLE IF EXISTS %I", resourceId))
+    sql.push("COMMIT")
+    return sql
+  }
+
+  createSchema(resourceId: string, props: EngineSchemaProperties): string | string[] {
+    const sql: string[] = [pgFormat("CREATE SCHEMA IF NOT EXISTS %I", resourceId)]
+    if (props?.RoleName) {
+      this.grantRoleForSchema(resourceId, props.RoleName).forEach((stmt) =>
+        sql.push(stmt)
+      )
+    }
+    return sql
+  }
+
+  updateSchema(
+    resourceId: string,
+    oldResourceId: string,
+    props: EngineSchemaProperties
+  ): string | string[] {
+    const statements: string[] = []
+    if (props?.RoleName) {
+      this.revokeRoleFromSchema(oldResourceId, props.RoleName).forEach((stmt) =>
+        statements.push(stmt)
+      )
+    }
+    if (resourceId !== oldResourceId) {
+      statements.push(pgFormat("ALTER SCHEMA %I RENAME TO %I", oldResourceId, resourceId))
+    }
+    if (props?.RoleName) {
+      this.grantRoleForSchema(resourceId, props.RoleName).forEach((stmt) =>
+        statements.push(stmt)
+      )
+    }
+    return statements
+  }
+
+  deleteSchema(resourceId: string, props: EngineSchemaProperties): string | string[] {
+    const statements: string[] = []
+    if (props?.RoleName) {
+      this.revokeRoleFromSchema(resourceId, props.RoleName).forEach((stmt) =>
+        statements.push(stmt)
+      )
+    }
+    statements.push(pgFormat("DROP SCHEMA IF EXISTS %I CASCADE", resourceId))
+    return statements
+  }
+
+  createSql(_resourceId: string, props: EngineSqlProperties): string | string[] {
+    if (!props.Statement) {
+      throw new Error("Statement is required for SQL resource")
+    }
+    return props.Statement
+  }
+
+  updateSql(
+    _resourceId: string,
+    _oldResourceId: string,
+    props: EngineSqlProperties
+  ): string | string[] {
+    if (!props.Statement) {
+      throw new Error("Statement is required for SQL resource")
+    }
+    return props.Statement
+  }
+
+  deleteSql(_resourceId: string, props: EngineSqlProperties): string | string[] {
+    if (props.Rollback) {
+      return props.Rollback
+    }
+    return []
+  }
+
+  createIamGrant(resourceId: string, props: EngineIamGrantProperties): string | string[] {
+    if (!props.ResourceArn) {
+      throw new Error("ResourceArn is required for IAM grant")
+    }
+    return pgFormat("AWS IAM GRANT %I TO %L", resourceId, props.ResourceArn)
+  }
+
+  updateIamGrant(
+    resourceId: string,
+    oldResourceId: string,
+    props: EngineIamGrantProperties,
+    oldProps: EngineIamGrantProperties
+  ): string | string[] {
+    const statements: string[] = []
+
+    // Revoke old grant if resource ARN or role name changed
+    if (oldProps.ResourceArn) {
+      statements.push(
+        pgFormat("AWS IAM REVOKE %I FROM %L", oldResourceId, oldProps.ResourceArn)
+      )
+    }
+
+    // Grant new permissions
+    if (props.ResourceArn) {
+      statements.push(pgFormat("AWS IAM GRANT %I TO %L", resourceId, props.ResourceArn))
+    }
+
+    return statements
+  }
+
+  deleteIamGrant(resourceId: string, props: EngineIamGrantProperties): string | string[] {
+    if (!props.ResourceArn) {
+      throw new Error("ResourceArn is required for IAM grant deletion")
+    }
+    return pgFormat("AWS IAM REVOKE %I FROM %L", resourceId, props.ResourceArn)
+  }
+
+  async executeSQL(sql: string | string[], config: EngineConnectionConfig): Promise<any> {
+    this.log("Connecting to DSQL cluster...")
+
+    // For DSQL, we need to generate an IAM auth token
+    const region = process.env.AWS_REGION
+    if (!region) {
+      throw new Error("AWS_REGION environment variable is required for DSQL")
+    }
+
+    const signer = new DsqlSigner({
+      hostname: config.host,
+      region: region,
+    })
+    const authToken = await signer.getDbConnectAdminAuthToken()
+
+    const clientConfig: ClientConfig = {
+      host: config.host,
+      port: config.port,
+      user: "admin", // DSQL always uses 'admin' user
+      password: authToken, // Use IAM auth token as password
+      database: "postgres", // DSQL always uses 'postgres' database
+      ssl: {
+        //ca: fs.readFileSync(`${process.env.LAMBDA_TASK_ROOT}/global-bundle.pem`),
+        rejectUnauthorized: true,
+      },
+      connectionTimeoutMillis: 30000,
+      query_timeout: 30000,
+      //statement_timeout: 30000, // not supported on DSQL
+    }
+
+    const client = new Client(clientConfig)
+
+    try {
+      await client.connect()
+      this.log("Connected to DSQL cluster")
+
+      const statements = Array.isArray(sql) ? sql : [sql]
+      const results = []
+
+      for (const statement of statements) {
+        if (statement.trim()) {
+          this.log(`Executing SQL: ${statement}`)
+          const result = await client.query(statement)
+          results.push(result)
+        }
+      }
+
+      this.log("SQL execution completed")
+      return results.length === 1 ? results[0] : results
+    } catch (error) {
+      this.log(`Error executing SQL: ${error}`)
+      throw error
+    } finally {
+      try {
+        await client.end()
+        this.log("Disconnected from DSQL cluster")
+      } catch (error) {
+        this.log(`Error disconnecting: ${error}`)
+      }
+    }
+  }
+
+  private grantRoleForSchema(schema: string, roleName: string): string[] {
+    return [
+      pgFormat("GRANT USAGE ON SCHEMA %I TO %I", schema, roleName),
+      pgFormat("GRANT CREATE ON SCHEMA %I TO %I", schema, roleName),
+    ]
+  }
+
+  private revokeRoleFromSchema(schema: string, roleName: string): string[] {
+    return [
+      pgFormat("REVOKE CREATE ON SCHEMA %I FROM %I", schema, roleName),
+      pgFormat("REVOKE ALL ON SCHEMA %I FROM %I", schema, roleName),
+    ]
+  }
+}

package/lambda/engine.factory.ts

@@ -1,10 +1,13 @@
 import { AbstractEngine } from "./engine.abstract"
+import { DsqlEngine } from "./engine.dsql"
 import { MysqlEngine } from "./engine.mysql"
 import { PostgresqlEngine } from "./engine.postgresql"
 
 export class EngineFactory {
   static createEngine(engine: string): AbstractEngine {
     switch (engine.toLowerCase()) {
+      case "dsql":
+        return new DsqlEngine()
       case "postgres":
       case "postgresql":
       case "aurora-postgresql":

package/lambda/engine.mysql.ts

@@ -5,6 +5,7 @@ import {
   EngineRoleProperties,
   EngineSchemaProperties,
   EngineSqlProperties,
+  EngineIamGrantProperties,
 } from "./types"
 
 export class MysqlEngine extends AbstractEngine {
@@ -183,6 +184,29 @@ export class MysqlEngine extends AbstractEngine {
     return props?.Rollback || ""
   }
 
+  createIamGrant(
+    _resourceId: string,
+    _props: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
+  updateIamGrant(
+    _resourceId: string,
+    _oldResourceId: string,
+    _props: EngineIamGrantProperties,
+    _oldProps: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
+  deleteIamGrant(
+    _resourceId: string,
+    _props: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
   async executeSQL(sql: string | string[], config: EngineConnectionConfig): Promise<any> {
     // Dynamic import to avoid bundling issues
     const { createConnection } = await import("mysql2/promise")

package/lambda/engine.postgresql.ts

@@ -8,6 +8,7 @@ import {
   EngineRoleProperties,
   EngineSchemaProperties,
   EngineSqlProperties,
+  EngineIamGrantProperties,
 } from "./types"
 
 export class PostgresqlEngine extends AbstractEngine {
@@ -267,6 +268,29 @@ END$$;`,
     ]
   }
 
+  createIamGrant(
+    _resourceId: string,
+    _props: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
+  updateIamGrant(
+    _resourceId: string,
+    _oldResourceId: string,
+    _props: EngineIamGrantProperties,
+    _oldProps: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
+  deleteIamGrant(
+    _resourceId: string,
+    _props: EngineIamGrantProperties
+  ): string | string[] {
+    throw new Error("IAM grants are only supported with DSQL clusters")
+  }
+
   async executeSQL(sql: string | string[], config: EngineConnectionConfig): Promise<any> {
     const isSslEnabled = process.env.SSL ? JSON.parse(process.env.SSL) : true
     const ssl: ConnectionOptions | false = isSslEnabled