DSQL
Serverless Postgres on Aurora DSQL. IAM auth over TLS, schemas and roles declared in code, and optional multi-region clusters.
Arguments
Names below are TypeScript (camelCase). In Python use snake_case (e.g. dataClassification → data_classification); in Go use PascalCase on the Args struct (e.g. DataClassification).
schemas array (DSQLSchema) Schemas, with their tables and roles. Anvil creates them for you; each field is explained under schemas below. Omit to manage tables yourself.
multiRegion object (DSQLMultiRegionArgs) Two linked, active-active clusters instead of one. Omit for a single cluster in the stack's region.
vpc object (DSQLVpcArgs) Keeps traffic from your Lambdas on private VPC endpoints instead of the public endpoint. Omit to use the public endpoint, which is still IAM-authenticated over TLS.
backup object (DSQLBackupArgs) Scheduled AWS Backup recovery points. Omit to disable; {} gives daily backups kept 35 days.
stream object (DSQLStreamArgs) Change data capture: every committed row change, in every table, sent to a Kinesis stream. See the Change data capture tab. Omit to keep CDC off.
pruneUnmanagedRoles boolean Also drop database roles that aren't in schemas and weren't created by Anvil, such as roles made by hand in SQL. Roles Anvil created are always dropped once they leave schemas. Default false: unmanaged roles are only reported when you deploy. admin and dbowner are never touched.
schemas 3 fields
Anvil creates each schema and everything in it. Tables are additive: new schemas, tables, columns and indexes are applied, but removing or changing one in code leaves the database as it is, and a type that no longer matches is reported when you deploy. A column added to an existing table can't have notNull or default: DSQL's ALTER TABLE ADD COLUMN takes only a name and a type, so the deploy fails with that reason. Declare them when the table is first created. Roles follow your code both ways: changing a role's grants or tableScoping re-grants it, and removing a role revokes its access and drops it. At most 10 schemas, and none named public (DSQL reserves it for admin).
name requiredstring Schema name, used as-is (not stage-prefixed). Must not be public.
tables array (DSQLTable) Tables in this schema. See schemas[].tables below.
roles array (DSQLRole) Postgres roles with privileges on this schema. See schemas[].roles below.
schemas[].tables 4 fields
At most 1,000 tables per database.
name requiredstring Table name, used as-is (not stage-prefixed).
columns requiredarray (DSQLColumn) The table's columns. See schemas[].tables[].columns below.
primaryKey requiredarray<string> Column names forming the primary key, in order. DSQL uses it to distribute rows and it can't be added or changed once the table exists, so choose it up front. AWS recommends a uuid generated in your app.
indexes array (DSQLIndex) Secondary indexes: { name, columns, unique? }. name is required. Built in the background with CREATE INDEX ASYNC, so a new index may not be used straight after a deploy.
schemas[].tables[].columns 8 fields
name requiredstring Column name.
type requiredstring One of uuid, text, varchar, char, boolean, smallint, integer, bigint, real, double precision, numeric, date, time, timestamp, timestamptz, interval, bytea, json, jsonb. DSQL has no arrays, enums, serial, money or xml.
notNull boolean Adds NOT NULL. Primary-key columns are always NOT NULL.
unique boolean Adds a unique index on this column.
default string A raw SQL default, used as-is: "now()", or "'active'" for a string (note the inner quotes).
length integer For char (up to 4096) and varchar (up to 65535).
precision integer Total digits for numeric, up to 38.
scale integer Digits after the decimal point for numeric, up to 37.
schemas[].roles 3 fields
A role is what a Lambda logs in as. Declaring it creates it; db.grantConnect(fn, { schemas: [{ schema, roleName }] }) lets a Lambda use it. Role names are database-wide, so they must be unique across all schemas.
name requiredstring Postgres role name, e.g. app_role.
grants requiredarray<string> Privileges on every current and future table in the schema, or only on the tableScoping tables when it is set: any of SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES.
tableScoping array<string> Limits grants to these tables instead of the whole schema, e.g. { name: 'orders_read', grants: ['SELECT'], tableScoping: ['orders'] } can read orders but no other table. Each table must be declared in this schema's tables, or the deploy fails. Tables you add later aren't covered, so add them to the list too. Changing the list revokes the role's old privileges and grants the new ones on the next deploy.
multiRegion 2 fields
Both clusters accept reads and writes with strong consistency. endpoint is the stack region's cluster; endpoints[region] gives either. AWS decides which region combinations are valid.
regions requiredarray<string> The two regions to create clusters in.
witnessRegion requiredstring A third region, different from both, that keeps a short window of encrypted transaction logs for durability.
vpc 3 fields
Anvil creates one interface endpoint (PrivateLink) per cluster region, with its own security group.
vpcId requiredstring The VPC, e.g. vpc.vpcId.
privateSubnetIds requiredarray<string> Subnets for the endpoint, usually one per availability zone, e.g. vpc.privateSubnetIds.
hasNat boolean Set when the VPC already has a NAT gateway: Anvil then creates no endpoints and traffic goes to the public endpoint through the NAT. Anvil never creates a NAT gateway. Default: false.
backup 4 fields
For multi-region clusters, recovery points are also copied to the other region so you can restore in either.
retentionDays integer Days to keep each recovery point. Default: 35.
scheduleExpression string When backups run, as a cron expression, e.g. "cron(0 2 * * ? *)". Default: daily at midnight.
scheduleTimezone string IANA timezone for the schedule, e.g. "Australia/Sydney". Default: "Etc/UTC".
vaultArn string An existing backup vault. Default: the account's default AWS Backup vault.
stream 3 fields
kinesisArn requiredstring The Kinesis stream that receives the events, e.g. a KinesisStream's arn. Must be in the stack's region and accept records of at least 2048 KiB (KinesisStream's default).
kmsKeyArn string The customer-managed KMS key the Kinesis stream is encrypted with, if it has one, so Anvil's role can use it. Not needed for KinesisStream's default key. Can't be combined with roleArn.
roleArn string Your own IAM role for DSQL to write with. Omit to have Anvil create one that only this cluster can assume and that can only write to kinesisArn.
This component also accepts a hatch argument to override the underlying resource
configuration. See Overrides & Escape Hatch.
Attributes
Outputs available once the resource is deployed.
endpoint string The cluster endpoint in the stack's region. For multi-region, use endpoints[region] for the other cluster.
endpoints map<string, string> Map of region to cluster endpoint.
clusterArns map<string, string> Map of region to cluster ARN.
rolesTableName string DynamoDB table name for role bootstrap. Passed to DSQLConnect. Empty when no roles are configured.
declaredRoles map<string, string> Map of each role declared in schemas to its schema. Passed to DSQLConnect, which only grants declared roles. Empty when schemas is omitted.
vpcEndpointIds map<string, string> Map of region to VPC endpoint ID. Only populated when vpc is set and hasNat is false.
vpcEndpointSecurityGroupIds map<string, string> Map of region to VPC endpoint security group ID. Only populated when vpc is set and hasNat is false.
streamKinesisArn string The Kinesis stream CDC events go to. Empty when stream is omitted.
streamRoleArn string The IAM role DSQL writes CDC events with: the one Anvil created, or stream.roleArn. Empty when stream is omitted.