Fjall Docs — deploy AWS infrastructure into your own account

Overview

The RdsAurora construct creates an Aurora Serverless v2 PostgreSQL cluster with a writer, one reader, automated backups, and storage encryption. RDS Proxy connection pooling, customer-managed KMS keys, and scheduled secret rotation are opt-in.

Resource Class

import { RdsAurora } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsAurora";

Basic Usage

const database = new RdsAurora(this, "MyDatabase", {
  vpc: myVpc,
  databaseName: "api",
});

Configuration Options

Core Properties

Property	Type	Description	Default
`vpc`	`IVpc`	VPC for deployment	Required
`databaseName`	`string`	Default database name	Construct ID
`clusterIdentifier`	`string`	Cluster identifier (lowercased for you)	`<kebab-construct-id>-cluster`
`port`	`number`	Database listener port	Engine default: `5432` (`3306` MySQL)

The port default comes from ENGINE_DEFAULT_DATABASE_PORTS in @fjall/generator. Keep it unless you have a reason to move: RDS Proxy accepts client connections only on the engine default, so a custom port behind a proxy makes getHostPort() report the proxy port, not the cluster port, and synth emits a warning explaining the split.

Engine Configuration

Property	Type	Description	Default
`engine`	`IClusterEngine`	Database engine	Aurora PostgreSQL 18.4
`engineVersion`	`string`	Version string the `engine` was built at	Engine default
`engineConfig`	`EngineConfig`	Engine family, default username, SSL parameter group	PostgreSQL defaults

The construct pins Aurora PostgreSQL 18.4. That pin moves with construct releases, so treat the version here as indicative and read rdsAurora.ts for the current value. engineVersion is only read to validate the auto-pause floor, so pass it whenever you set serverlessV2MinCapacity: 0.

Serverless v2 Capacity

Property	Type	Description	Default
`serverlessV2MinCapacity`	`number`	Capacity floor in ACU. `0` auto-pauses	AWS default
`serverlessV2MaxCapacity`	`number`	Capacity ceiling in ACU	AWS default
`serverlessV2AutoPauseDuration`	`Duration`	Idle time before pausing to 0 ACU	Not configured
`enableDataApi`	`boolean`	Enables the RDS Data API HTTP endpoint	`false`

Synth rejects a min capacity above the max, an auto-pause duration outside 5 minutes to 24 hours, and serverlessV2MinCapacity: 0 on an engineVersion below 16.3.

Writer Configuration

Property	Type	Description	Default
`writer`	`AuroraWriterConfig`	Writer instance config	Serverless v2

AuroraWriterConfig accepts enableDatabaseInsights, identifierSuffix, and availabilityZone.

Reader Configuration

Property	Type	Description	Default
`readers`	`AuroraReadersConfig \| false`	Reader instances	1 serverless v2 reader

Set count for identical readers or instances for per-reader configuration. The two are mutually exclusive. The first reader scales with the writer. Pass false for a cluster with no readers.

Proxy Configuration

Property	Type	Description	Default
`proxy`	`ProxyConfig \| false`	RDS Proxy for connection pooling	Not created

ProxyConfig fields: requireTLS (default true), connectionBorrowTimeout in seconds (default 120), maxConnections and maxIdleConnections as percentages of the cluster maximum, and vpcSubnets (default private with egress).

Backup and Maintenance

Property	Type	Description	Default
`backupRetention`	`number`	Backup retention in days	`14`
`monitoringInterval`	`Duration`	Enhanced monitoring interval	1 minute
`preferredMaintenanceWindow`	`string`	Maintenance window	`"Sat:12:30-Sat:20:30"`
`removalPolicy`	`RemovalPolicy`	Behaviour when the stack is deleted	`SNAPSHOT`

RemovalPolicy.SNAPSHOT takes a final snapshot on delete. DESTROY is for disposable-data clusters only: the delete takes the data with it, with no snapshot and no recovery. Tags are copied to every automated and manual snapshot.

Security

Property	Type	Description	Default
`encryption`	`AuroraEncryptionConfig`	Storage encryption key	AWS-managed key (`aws/rds`)
`credentials`	`CredentialsConfig`	Master username and rotation opt-in	Engine default username
`deletionProtection`	`boolean`	Prevent accidental deletion	`true`
`allowVpcAccess`	`boolean`	Allow access from the whole VPC CIDR	`false`
`publiclyAccessible`	`boolean`	Place the cluster in public subnets	`false`
`allowedIpCidr`	`string`	CIDR to allow when publicly accessible	None

IAM database authentication is enabled on every cluster.

Snapshot Restore

Property	Type	Description	Default
`snapshotIdentifier`	`string`	Cluster snapshot identifier or ARN	None
`snapshotUsername`	`string`	Master username from the snapshot	None

Database Insights

Property	Type	Description	Default
`databaseInsights`	`DatabaseInsightsConfig \| false`	Performance monitoring	Enabled

DatabaseInsightsConfig accepts mode ("standard" or "advanced", default "standard") and encryptionKey.

Alarms

Property	Type	Description	Default
`alertsTopic`	`ITopic`	SNS topic for alarm notifications	None
`alarms`	`RdsAlarmThresholds \| false`	Threshold overrides, `false` to skip	Fjall defaults
`applicationId`	`string`	Application ID for alarm tagging	None

Alarms are created only when alertsTopic is supplied.

Default Architecture

Passing nothing but vpc and databaseName creates:

1 writer instance (Serverless v2)
1 reader instance (Serverless v2, scaling with the writer)
Storage encryption with the AWS-managed KMS key aws/rds
Database Insights in standard mode
14-day automated backups, tags copied to snapshots
Deletion protection on, removal policy SNAPSHOT
IAM database authentication

RDS Proxy is not created by default. Pass a proxy configuration to enable it. Secret rotation is not enabled by default. Opt in with credentials: { secretRotation: {} } for the 30-day default, or { automaticallyAfterDays: 7 } to shorten it.

Rotation uses the multi-user strategy, which needs a one-time manual step after deploy: populate the generated <construct-id>/master-secret with valid superuser credentials as JSON. Until you do, every rotation attempt fails and the database password stays unchanged. Synth emits a warning to the same effect whenever rotation is enabled.

Encryption

Storage encryption is always on. By default the cluster uses the AWS-managed KMS key aws/rds, which you cannot rotate, scope, or revoke yourself. Pass the USE_CMK marker to create a Fjall-managed customer-managed key instead.

import { RdsAurora } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsAurora";
import { USE_CMK } from "@fjall/components-infrastructure";

const database = new RdsAurora(this, "Database", {
  vpc: myVpc,
  databaseName: "api",
  encryption: { storageKey: USE_CMK },
  databaseInsights: { encryptionKey: USE_CMK },
});

You can also pass an existing IKey in place of USE_CMK.

Changing encryption.storageKey after creation replaces the cluster. Decide before the first deploy.

The storage key is created with protects: "outlives-stack", because the SNAPSHOT removal policy leaves a final snapshot behind and destroying its key would make that snapshot permanently unrestorable.

Network Security

The cluster is placed in private subnets with egress. Its security group starts closed, so grant access explicitly.

const database = new RdsAurora(this, "Database", {
  vpc: myVpc,
  databaseName: "api",
});

// Preferred: uses the construct's own default port, so it cannot drift
database.connections.allowDefaultPortFrom(service, "API service to database");

Set allowVpcAccess: true to open the database port to the entire VPC CIDR, which avoids cross-stack cyclic dependencies with Lambda.

publiclyAccessible: true moves the cluster into public subnets. Pair it with a narrow allowedIpCidr such as "203.0.113.4/32". Setting allowedIpCidr: "0.0.0.0/0" opens the database port to the entire internet and synth warns about it.

Reader Configuration

Default (1 reader)

const database = new RdsAurora(this, "Database", {
  vpc: myVpc,
  databaseName: "api",
});

Multiple readers

const database = new RdsAurora(this, "ScaledDatabase", {
  vpc: myVpc,
  databaseName: "api",
  readers: { count: 3 },
});

Per-reader configuration

const database = new RdsAurora(this, "ZonalReaders", {
  vpc: myVpc,
  databaseName: "api",
  readers: {
    instances: [
      { scaleWithWriter: true },
      { availabilityZone: "eu-west-1b", enableDatabaseInsights: false },
    ],
  },
});

No readers

const database = new RdsAurora(this, "WriterOnly", {
  vpc: myVpc,
  databaseName: "api",
  readers: false,
});

Scale to Zero

Set serverlessV2MinCapacity: 0 with an auto-pause duration to let an idle cluster pause and bill nothing for compute. This needs Aurora PostgreSQL 16.3 or later, and you must pass engineVersion so synth can check the floor.

import { Duration } from "aws-cdk-lib";

const database = new RdsAurora(this, "DevDatabase", {
  vpc: myVpc,
  databaseName: "api",
  engineVersion: "18.4",
  serverlessV2MinCapacity: 0,
  serverlessV2MaxCapacity: 4,
  serverlessV2AutoPauseDuration: Duration.minutes(20),
  enableDataApi: true,
});

A live pooled connection pins the cluster above 0 ACU, so pair auto-pause with enableDataApi: true when the workload can run DDL over HTTPS instead of holding a VPC connection.

RDS Proxy

Enable RDS Proxy for connection pooling, faster failover, and fewer database connections.

const database = new RdsAurora(this, "ProxiedDatabase", {
  vpc: myVpc,
  databaseName: "api",
  proxy: {
    requireTLS: true,
    connectionBorrowTimeout: 120,
    maxConnections: 80,
    maxIdleConnections: 50,
  },
});

// With a proxy, getHostEndpoint() returns the proxy endpoint
const endpoint = database.getHostEndpoint();

maxConnections and maxIdleConnections are percentages of the cluster’s connection limit, not absolute counts. Enabling the proxy repoints database.connections at the proxy security group, so existing allowDefaultPortFrom grants keep working. Without a proxy, getHostEndpoint() returns the cluster writer endpoint.

Restoring from Snapshot

Create a new Aurora cluster from an existing cluster snapshot.

const database = new RdsAurora(this, "RestoredCluster", {
  vpc: myVpc,
  databaseName: "restored",
  snapshotIdentifier: "rds:api-cluster-snapshot",
  snapshotUsername: "postgres",
});

Key constraints when restoring from a snapshot:

The master username is immutable and baked into the snapshot. snapshotUsername must match the original cluster’s username exactly. Omit it and synth warns that it assumed a username.
The engine version is inherited from the snapshot. A mismatch between the snapshot’s engine version and the infrastructure code causes a CloudFormation failure.
The master password is reset shortly after the restore. Fjall generates a new credentials secret for the restored cluster, and CloudFormation applies its password once the cluster becomes available (the cluster briefly reports resetting-master-credentials). The snapshot-era password stops working at that point, so applications must read credentials from the generated secret.

This password reset applies only to restores performed through infrastructure code (snapshotIdentifier). Restores performed through AWS Backup (fjall restore rds) run outside CloudFormation and keep the snapshot-era password. See fjall restore.

Backup and Recovery

Custom backup retention

const database = new RdsAurora(this, "BackupDatabase", {
  vpc: myVpc,
  databaseName: "api",
  backupRetention: 30,
});

Point-in-time recovery

Aurora supports PITR for any point within the backup retention window:

Continuous backup to S3
Restore to any second within the retention window
Cross-region backup replication available

Monitoring

Enhanced monitoring

import { Duration } from "aws-cdk-lib";

const database = new RdsAurora(this, "MonitoredDatabase", {
  vpc: myVpc,
  databaseName: "api",
  monitoringInterval: Duration.seconds(10),
});

Database Insights

Enabled on every instance by default in standard mode. It reports:

SQL-level performance metrics
Top SQL statements
Database load by wait event

Pass databaseInsights: { mode: "advanced" } for longer retention, or databaseInsights: false to turn it off.

Methods

Method	Returns	Description
`getHostEndpoint()`	`string`	Proxy endpoint when a proxy exists, otherwise the cluster endpoint
`getHostPort()`	`string`	Client-facing port as a string (`"5432"` by default)
`getConnectionString()`	`string`	`postgresql://<endpoint>:<port>/<database>`
`getCredentials()`	`Secret`	Generated credentials secret (`<construct-id>/credentials`)
`getDatabaseName()`	`string`	Default database name
`getClusterIdentifier()`	`string`	Physical cluster identifier
`getBackupRetentionDays()`	`number`	Applied backup retention in whole days
`getSnapshotTarget()`	`{ kind: "cluster"; arn: string }`	Cluster ARN for backup plans and the migration runner
`getDatabaseCluster()`	`DatabaseCluster`	Underlying CDK L2 construct
`getCfnCluster()`	`CfnDBCluster \| undefined`	Underlying L1 construct for escape hatches

database.connections is a public Connections property, not a method. Use it for security-group grants.

const endpoint = database.getHostEndpoint();
const port = database.getHostPort();
const credentials = database.getCredentials();
const connectionString = database.getConnectionString();

Complete Example

import { RdsAurora } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsAurora";
import { USE_CMK } from "@fjall/components-infrastructure";
import { CfnOutput, Duration } from "aws-cdk-lib";
import { Vpc } from "aws-cdk-lib/aws-ec2";

const vpc = new Vpc(this, "AppVpc", {
  maxAzs: 3,
  natGateways: 1,
});

const database = new RdsAurora(this, "ProductionDatabase", {
  vpc,
  databaseName: "api",
  clusterIdentifier: "api-prod-cluster",

  // Backup and maintenance
  backupRetention: 35,
  preferredMaintenanceWindow: "Sun:03:00-Sun:04:00",

  // Monitoring
  monitoringInterval: Duration.seconds(10),

  // Customer-managed encryption
  encryption: { storageKey: USE_CMK },

  // Connection pooling
  proxy: { requireTLS: true },

  // Read scaling
  readers: { count: 2 },
});

// Grant the API service access on the construct's own default port
database.connections.allowDefaultPortFrom(
  apiService,
  "API service to database",
);

new CfnOutput(this, "DatabaseEndpoint", {
  value: database.getHostEndpoint(),
  description: "Database endpoint (proxy when enabled)",
});

Cost Optimisation

Serverless v2 bills per ACU-second, so cost tracks the capacity floor you set rather than an instance size.

Configuration	Monthly compute (indicative)
Auto-paused (min 0 ACU)	~$0 while paused
0.5 ACU floor	~$44
1 ACU floor	~$87
2 ACU floor	~$174
Each additional reader	Adds one instance’s capacity

Figures are us-east-1 list price for compute only. Storage, I/O, backups beyond the free allowance, and RDS Proxy are billed separately, and prices vary by region. Three levers matter most:

Set serverlessV2MinCapacity deliberately. The floor is what you pay when idle.
Use auto-pause for development and preview clusters.
Drop readers you do not query, using readers: false or a lower count.

Best Practices

Enable RDS Proxy when the application opens many short-lived connections.
Grant access with allowDefaultPortFrom rather than a hardcoded port.
Pass encryption: { storageKey: USE_CMK } when you need a key you can rotate and revoke.
Match backupRetention to your recovery objective (default 14 days).
Route analytics and reporting queries at readers.
Watch ACU usage and tune the capacity floor.
Keep deletionProtection and the SNAPSHOT removal policy on for production.

Limitations

The capacity floor is 0.5 ACU unless auto-pause is enabled (serverlessV2MinCapacity: 0), which requires Aurora PostgreSQL 16.3 or later.
Auto-pause duration must be between 5 minutes and 24 hours.
RDS Proxy accepts client connections only on the engine default port. AWS does not allow configuring the proxy listener port.
The engine is pinned to Aurora PostgreSQL 18.4. Major version upgrades need planning.
Cross-region replicas need a Global Database. See RdsAuroraGlobal.
Changing the storage encryption key after creation replaces the cluster.

Next Steps

RDS Instance

Deploy a single-instance PostgreSQL or MySQL database when you do not need Serverless v2 scaling.

Database Factory

Provision Aurora, RDS Instance, DynamoDB, or ClickHouse from one declarative factory.

Security Group

Control which services and CIDRs can reach the cluster on port 5432.

KMS Key

Create and scope the customer-managed key that encrypts cluster storage.

Secrets Manager

Read the generated database credentials and configure rotation.

fjall restore

Restore an Aurora cluster from an AWS Backup recovery point.

​Overview

​Resource Class

​Basic Usage

​Configuration Options

​Core Properties

​Engine Configuration

​Serverless v2 Capacity

​Writer Configuration

​Reader Configuration

​Proxy Configuration

​Backup and Maintenance

​Security

​Snapshot Restore

​Database Insights

​Alarms

​Default Architecture

​Encryption

​Network Security

​Reader Configuration

​Default (1 reader)

​Multiple readers

​Per-reader configuration

​No readers

​Scale to Zero

​RDS Proxy

​Restoring from Snapshot

​Backup and Recovery

​Custom backup retention

​Point-in-time recovery

​Monitoring

​Enhanced monitoring

​Database Insights

​Methods

​Complete Example

​Cost Optimisation

​Best Practices

​Limitations

​Next Steps

RDS Instance

Database Factory

Security Group

KMS Key

Secrets Manager

fjall restore

Overview

Resource Class

Basic Usage

Configuration Options

Core Properties

Engine Configuration

Serverless v2 Capacity

Writer Configuration

Reader Configuration

Proxy Configuration

Backup and Maintenance

Security

Snapshot Restore

Database Insights

Alarms

Default Architecture

Encryption

Network Security

Reader Configuration

Default (1 reader)

Multiple readers

Per-reader configuration

No readers

Scale to Zero

RDS Proxy

Restoring from Snapshot

Backup and Recovery

Custom backup retention

Point-in-time recovery

Monitoring

Enhanced monitoring

Database Insights

Methods

Complete Example

Cost Optimisation

Best Practices

Limitations

Next Steps