AWS.DSQL reference

Cluster

Source: src/AWS/DSQL/Cluster.ts

An Amazon Aurora DSQL cluster — a serverless, distributed SQL database with active-active high availability and Postgres wire compatibility.

Clusters are pay-per-use with no provisioned capacity, so they have excellent test economics. Create is asynchronous (CREATING -> ACTIVE), usually completing in under a minute; the provider waits for ACTIVE (bounded) before returning.

Cluster: Creating a Cluster

Basic Cluster

const cluster = yield* Cluster("AppDb", {});
// connect to cluster.endpoint on port 5432 as user "admin"

Cluster with Deletion Protection

const cluster = yield* Cluster("AppDb", {
  deletionProtectionEnabled: true,
});

Cluster with a Customer-Managed KMS Key

const cluster = yield* Cluster("AppDb", {
  kmsEncryptionKey: key.keyArn,
});

ClusterPolicy

Source: src/AWS/DSQL/ClusterPolicy.ts

The resource-based policy of an Aurora DSQL cluster — controls which principals may perform actions on the cluster (most commonly gating dsql:DbConnect / dsql:DbConnectAdmin behind VPC or Organization conditions). A cluster has at most one.

ClusterPolicy: Creating a Cluster Policy

Block Connections from Outside a VPC

const cluster = yield* DSQL.Cluster("AppDb", {});
const policy = yield* DSQL.ClusterPolicy("VpcOnly", {
  clusterId: cluster.clusterId,
  policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Deny",
        Principal: { AWS: "*" },
        Action: ["dsql:DbConnect", "dsql:DbConnectAdmin"],
        Resource: "*",
        Condition: { Null: { "aws:SourceVpc": "true" } },
      },
    ],
  }),
});

Restrict Access to an AWS Organization

const policy = yield* DSQL.ClusterPolicy("OrgOnly", {
  clusterId: cluster.clusterId,
  policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Deny",
        Principal: { AWS: "*" },
        Action: ["dsql:DbConnect", "dsql:DbConnectAdmin"],
        Resource: "*",
        Condition: {
          StringNotEquals: { "aws:PrincipalOrgID": "o-exampleorgid" },
        },
      },
    ],
  }),
});

Connect

Source: src/AWS/DSQL/Connect.ts

Runtime binding that resolves connection settings for an Aurora DSQL cluster using IAM database authentication.

DSQL clusters expose a public Postgres-wire endpoint (<clusterId>.dsql.<region>.on.aws:5432) and authenticate exclusively with short-lived IAM auth tokens — there is no password secret and no VPC requirement. The deploy half grants dsql:DbConnect (or dsql:DbConnectAdmin with admin: true) on the cluster to the host Function; the runtime half mints a presigned token client-side (a pure SigV4 computation, no API call) and returns a SqlConnectionInfo whose url feeds Drizzle.Postgres / any Postgres client directly.

Token freshness is structural: yielding the returned connection effect re-mints the token, and execution-scoped pools (Drizzle.Postgres) rebuild per execution — a ~15-minute token can never outlive its pool.

Connect: Connecting to a Cluster

Resolve Connection Info inside a Function

const conn = yield* DSQL.Connect(cluster, { admin: true });
// inside a handler — each yield mints a fresh auth token:
const { host, port, username, password, url } = yield* conn;

Drizzle over DSQL

const conn = yield* DSQL.Connect(cluster, { admin: true });
const db = yield* Drizzle.Postgres(conn.pipe(Effect.map((info) => info.url)));
// inside a handler:
const rows = yield* db.select().from(Widgets);

Connect as a Custom Database Role

const conn = yield* DSQL.Connect(cluster, {
  username: "app",
  database: "postgres",
});

GetVpcEndpointServiceName

Source: src/AWS/DSQL/GetVpcEndpointServiceName.ts

Retrieves the VPC endpoint service name of an Aurora DSQL cluster — the com.amazonaws.{region}.dsql-{suffix} PrivateLink service name used to create a VPC interface endpoint that reaches the cluster privately.

Bind a Cluster inside a function runtime to look the name up on demand (e.g. from an operations function that provisions VPC endpoints). Provide DSQL.GetVpcEndpointServiceNameHttp on the Function effect to implement the binding.

GetVpcEndpointServiceName: Resolving the VPC Endpoint Service Name

// init
const getVpcEndpointServiceName =
  yield* DSQL.GetVpcEndpointServiceName(cluster);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const { serviceName } = yield* getVpcEndpointServiceName();
    return HttpServerResponse.json({ serviceName });
  }),
};

Stream

Source: src/AWS/DSQL/Stream.ts

A change data capture (CDC) stream on an Aurora DSQL cluster — delivers committed row-level changes (Debezium-shaped JSON envelopes) to an Amazon Kinesis data stream.

Creation is asynchronous (CREATING -> ACTIVE, typically one to three minutes); the provider waits for ACTIVE (bounded) before returning. A stream has no update operation — every property except tags replaces it.

Functions consume the change records through the existing Kinesis event source on the target stream; DSQL itself never invokes compute directly.

Stream: Creating a CDC Stream

Stream Cluster Changes into Kinesis

const cluster = yield* DSQL.Cluster("AppDb", {});
const target = yield* Kinesis.Stream("Changes", {
  streamMode: "ON_DEMAND",
  maxRecordSizeInKiB: 10240,
});
const role = yield* IAM.Role("CdcRole", {
  assumeRolePolicyDocument: JSON.stringify({
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { Service: "dsql.amazonaws.com" },
        Action: "sts:AssumeRole",
      },
    ],
  }),
  inlinePolicies: {
    kinesis: JSON.stringify({
      Version: "2012-10-17",
      Statement: [
        {
          Effect: "Allow",
          Action: [
            "kinesis:PutRecord",
            "kinesis:PutRecords",
            "kinesis:DescribeStreamSummary",
            "kinesis:ListShards",
          ],
          Resource: target.streamArn,
        },
      ],
    }),
  },
});
const cdc = yield* DSQL.Stream("Cdc", {
  clusterId: cluster.clusterId,
  kinesisStreamArn: target.streamArn,
  roleArn: role.roleArn,
});

Consume Change Records with a Function

// DSQL delivers into the Kinesis stream; consume it with the
// Kinesis event source on the target stream.
yield* Kinesis.consume(target, (records) =>
  Effect.forEach(records, (record) => handleChange(record)),
);