Fjall Docs — deploy AWS infrastructure into your own account

Overview

RdsInstance provisions a managed PostgreSQL database instance with Multi-AZ deployment, storage encryption, automated backups, IAM database authentication, and optional RDS Proxy pooling and read replicas. Pick it over Aurora when you want predictable, fixed-size capacity and a lower floor price. Aurora suits variable or bursty workloads.

Add a database from the CLI

fjall add database --app api --name AppDb --type Instance --databaseName appdb

Four inputs are mandatory on fjall add database:

Flag	Purpose
`--app`	Application whose `infrastructure.ts` is edited
`--name`	Resource name in the file (must start with a letter)
`--type`	`Instance`, `Aurora`, `GlobalAurora`, or `ClickHouse`
`--databaseName`	Initial database name created inside the instance

Add --tier <name> to expand a preset into the emitted properties, where the name is tinkerer, lightweight, standard, resilient, or enterprise. On fjall add database the tier flag also requires --type, because each tier describes each database type differently.

Import the construct

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

Basic usage

const database = new RdsInstance(this, "AppDb", {
  vpc,
  databaseName: "appdb",
  instanceType: "t4g.medium",
});

instanceType takes the bare class.size form (t4g.medium, r7g.large), not the db.-prefixed form. The construct passes the value straight to new InstanceType(...), so a db. prefix produces an invalid instance class.

Configuration options

Core properties

Property	Type	Description	Default
`vpc`	`IVpc`	VPC the instance is deployed into	Required
`databaseName`	`string`	Initial database name	Construct ID with the first `Rds` removed
`port`	`number`	Listener port	Engine default (`5432` PostgreSQL, `3306` MySQL)
`engine`	`IInstanceEngine`	CDK engine object	PostgreSQL 17.9
`engineConfig`	`EngineConfig`	Engine family, master username, SSL parameters	PostgreSQL, `postgres`, `rds.force_ssl=1`

The instance identifier is derived from the construct ID in kebab case, so ProductionDatabase becomes production-database. It is not settable through props.

Instance sizing

Property	Type	Description	Default
`instanceType`	`string`	Instance type (bare `class.size`)	`"t4g.large"`
`allocatedStorage`	`number`	Initial storage in GiB	`100`
`maxAllocatedStorage`	`number`	Storage autoscaling ceiling in GiB	`500`
`multiAz`	`boolean`	Multi-AZ deployment	`true`
`publiclyAccessible`	`boolean`	Place the instance in a public subnet	`false`
`deletionProtection`	`boolean`	RDS deletion protection	`true`

When Fjall provisions a database through an application tier, the instance type comes from the tier preset: t4g.micro (Tinkerer), t4g.small (Lightweight), t4g.large (Standard), r7g.large (Resilient), r7g.xlarge (Enterprise). Using the construct directly, set instanceType yourself.

Backup and maintenance

Property	Type	Description	Default
`backupRetention`	`Duration`	Automated backup retention	14 days
`preferredBackupWindow`	`string`	Daily backup window (UTC)	`"02:00-03:00"`
`preferredMaintenanceWindow`	`string`	Weekly maintenance window (UTC)	`"Sat:12:30-Sat:20:30"`
`monitoringInterval`	`Duration`	Enhanced monitoring granularity	1 minute

backupRetention must be a whole number of days. A fractional Duration throws at synth.

Security

Property	Type	Description	Default
`credentials`	`CredentialsConfig`	Master username and opt-in secret rotation	Engine default username, rotation off
`encryption`	`EncryptionConfig`	`storageKey` spec for storage encryption	AWS-managed key
`iamAuthentication`	`boolean`	RDS IAM database authentication	`true`

Snapshot restore

Property	Type	Description	Default
`snapshotIdentifier`	`string`	RDS snapshot identifier or ARN to restore from	-
`snapshotUsername`	`string`	Master username baked into the snapshot	-

Optional features

Property	Type	Description	Default
`proxy`	`ProxyConfig \| false`	RDS Proxy connection pooling	Disabled
`readReplica`	`ReadReplicaConfig \| false`	Read replica	Disabled
`databaseInsights`	`DatabaseInsightsConfig \| false`	Database Insights monitoring	Enabled (standard mode)
`alertsTopic`	`ITopic`	SNS topic for CloudWatch alarms	No alarms
`alarms`	`RdsAlarmThresholds \| false`	Alarm threshold overrides	Defaults, when `alertsTopic` is set
`applicationId`	`string`	Application ID used to tag alarms	-

Two props are accepted by the TypeScript interface but never read by the construct: securityGroupIds and clusterIdentifier. Passing either changes nothing. Use database.connections or database.databaseSecurityGroup for network wiring, and rely on the derived instance identifier.

Ports and connectivity

The listener port comes from the engine family, so a PostgreSQL instance listens on 5432 unless you set port explicitly. The construct opens a self-referencing ingress rule on that port and exposes a Connections object with the same default. Grant access with the default port rather than a literal, so the wiring stays correct if the port or the proxy changes:

database.connections.allowDefaultPortFrom(app, "Application to database");

RDS Proxy accepts client connections only on the engine-default port, because the CreateDBProxy API has no port parameter. If you set a custom port and also enable proxy, direct database access uses your custom port while the proxy listens on the engine default. getHostPort() and database.connections then advertise the proxy port, and synth emits a warning naming both.

Security

Encryption

Storage encryption is always on. The default key is the AWS-managed RDS key. Pass encryption.storageKey to request a customer-managed key (CMK), which Fjall creates and retains beyond the stack so final snapshots stay restorable.

import { USE_CMK } from "@fjall/components-infrastructure";

const database = new RdsInstance(this, "SecureDb", {
  vpc,
  databaseName: "secure",
  encryption: { storageKey: USE_CMK },
});

The Resilient and Enterprise tier presets request a CMK for both storage and Database Insights. Lower tiers use the AWS-managed key.

IAM database authentication

IAM authentication is on by default. It costs nothing and grants nothing until you call grantIamConnect, and password authentication keeps working alongside it.

database.grantIamConnect(taskRole, "app_user");

The grant scopes rds-db:connect to the exact dbuser:<dbiResourceId>/<username> ARN. Calling it on an instance that opted out with iamAuthentication: false throws at synth.

Credentials

Fjall generates a Secrets Manager secret named <ConstructId>/credentials holding the master username and a generated password. Read it with getCredentials() and import individual fields into a container:

const dbPassword = database.getCredentials().getImport("password");

Multi-user secret rotation is opt-in. Pass a configuration object to switch it on, where {} accepts the 30-day default:

const database = new RdsInstance(this, "RotatedDb", {
  vpc,
  databaseName: "rotated",
  credentials: {
    username: "postgres",
    secretRotation: { automaticallyAfterDays: 30 },
  },
});

Network placement

Instances land in private subnets with egress. Setting publiclyAccessible: true moves them to public subnets, which is how the Tinkerer tier runs without a NAT gateway.

High availability

Multi-AZ is on by default. Set multiAz: false to opt out, which the Tinkerer and Lightweight presets do.

const database = new RdsInstance(this, "HaDb", {
  vpc,
  databaseName: "highavail",
  multiAz: true,
});

Multi-AZ gives you:

Automatic failover, typically in 1 to 2 minutes
Synchronous replication to the standby
Patching applied to the standby first
Higher durability

RDS Proxy

Pass a ProxyConfig object to add connection pooling. Fields: requireTLS, maxConnections, maxIdleConnections, connectionBorrowTimeout (seconds), vpcSubnets.

const database = new RdsInstance(this, "PooledDb", {
  vpc,
  databaseName: "pooled",
  proxy: {
    requireTLS: true,
    connectionBorrowTimeout: 120,
  },
});

const endpoint = database.getHostEndpoint();

With a proxy enabled, getHostEndpoint() returns the proxy endpoint and database.connections targets the proxy security group. requireTLS defaults to true and the borrow timeout defaults to 120 seconds. The proxy name is the kebab-case construct ID plus -proxy.

Read replicas

Pass a ReadReplicaConfig object to add one replica. Fields: instanceType, availabilityZone. Pass {} to inherit the primary’s instance type.

const database = new RdsInstance(this, "ScaledDb", {
  vpc,
  databaseName: "scaled",
  readReplica: {
    instanceType: "r7g.large",
  },
});

The replica inherits the primary’s storage settings, Multi-AZ flag, monitoring interval, maintenance window, deletion protection, and IAM authentication setting. Its identifier is the kebab-case construct ID plus -read-replica. Replication is asynchronous, so replica reads lag the primary. A deletion waiter custom resource holds stack deletion until the primary reports available, because deleting a replica puts the primary into modifying and the final snapshot would otherwise fail.

Database Insights

Database Insights (formerly Performance Insights) is on in standard mode by default. Pass a config object to change the mode, or false to switch it off. Fields: mode ("standard" or "advanced"), encryptionKey.

const database = new RdsInstance(this, "MonitoredDb", {
  vpc,
  databaseName: "monitored",
  databaseInsights: {
    mode: "advanced",
  },
});

Mode	Retention	Use for
`standard`	7 days	Day-to-day query and wait-event inspection
`advanced`	15 months	Long-run regression analysis and capacity planning

Backups and restore

Automated backups run daily in the backup window and support point-in-time recovery. Transaction logs are captured continuously. Automated backups are retained when the instance is deleted, and the removal policy takes a final snapshot on stack deletion.

const database = new RdsInstance(this, "BackupDb", {
  vpc,
  databaseName: "backup",
  backupRetention: Duration.days(30),
  preferredBackupWindow: "02:00-03:00",
});

Restoring from a snapshot

const database = new RdsInstance(this, "RestoredDb", {
  vpc,
  databaseName: "restored",
  snapshotIdentifier: "rds:my-production-snapshot",
  snapshotUsername: "postgres",
});

The same restore configured from the CLI:

fjall add database --app api --name RestoredDb --type Instance \
  --databaseName restored \
  --snapshotIdentifier rds:my-production-snapshot \
  --snapshotUsername postgres

Constraints when restoring from a snapshot:

The master username is immutable and baked into the snapshot. snapshotUsername must match the original database’s username exactly. Omitting it falls back to credentials.username or the engine default and raises a synth warning.
The engine version is inherited from the snapshot. A mismatch between the snapshot’s engine version and the infrastructure code causes a CloudFormation failure.
Storage cannot be smaller than the snapshot’s allocated storage.
The master password is reset shortly after the restore. Fjall generates a new credentials secret and CloudFormation applies its password once the instance becomes available (the instance briefly reports resetting-master-credentials). The snapshot-era password stops working at that point, so applications must read credentials from the generated secret.

The 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. Reconcile the credentials, then run fjall rollout <app> so running containers pick up the new values. See fjall restore.

Methods

Method	Returns	Description
`getHostEndpoint()`	`string`	Proxy endpoint when a proxy is enabled, otherwise the instance endpoint
`getHostPort()`	`string`	Client-facing port as a string
`getDatabaseName()`	`string`	Resolved database name
`getConnectionString()`	`string`	`postgresql://<endpoint>:<port>/<database>`, without credentials
`getCredentials()`	`Secret`	Credentials secret holding username and password
`getInstanceIdentifier()`	`string`	RDS instance identifier
`getBackupRetentionDays()`	`number`	Applied backup retention in whole days
`getSnapshotTarget()`	`object`	Snapshot target descriptor for backup plans
`grantIamConnect()`	`Grant`	Grants `rds-db:connect` for one database username

Two properties are also public: connections (a CDK Connections object) and databaseSecurityGroup.

Complete example

import { RdsInstance } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsInstance";
import EcsCluster from "@fjall/components-infrastructure/lib/resources/aws/compute/ecs";
import { Duration, CfnOutput } from "aws-cdk-lib";
import { Vpc } from "aws-cdk-lib/aws-ec2";

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

const database = new RdsInstance(this, "ProductionDatabase", {
  vpc,
  databaseName: "production",

  // Sizing
  instanceType: "r7g.large",
  allocatedStorage: 200,
  maxAllocatedStorage: 1000,

  // Connection pooling and read scaling
  proxy: { requireTLS: true },
  readReplica: { instanceType: "r7g.large" },

  // Monitoring
  databaseInsights: { mode: "advanced" },
  monitoringInterval: Duration.seconds(10),

  // Backup
  backupRetention: Duration.days(30),
  preferredMaintenanceWindow: "Sun:03:00-Sun:04:00",
});

const app = new EcsCluster(this, "Api", {
  clusterName: "api",
  appName: "api",
  vpc,
  ecrRepository: "api",
  services: [
    {
      name: "api",
      capacityProvider: "FARGATE",
      containers: [
        {
          name: "api",
          port: 3000,
          environment: {
            DB_HOST: database.getHostEndpoint(),
            DB_PORT: database.getHostPort(),
            DB_NAME: database.getDatabaseName(),
          },
          secretsImport: {
            DB_PASSWORD: database.getCredentials().getImport("password"),
          },
        },
      ],
    },
  ],
});

database.connections.allowDefaultPortFrom(app, "API service to database");

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

Cost optimisation

Instance sizing

Instance type	vCPUs	Memory	Monthly cost*
t4g.micro	2	1 GiB	~$12
t4g.small	2	2 GiB	~$23
t4g.medium	2	4 GiB	~$46
m7g.large	2	8 GiB	~$110
r7g.large	2	16 GiB	~$140
r7g.xlarge	4	32 GiB	~$280

*Rough on-demand estimates for us-east-1, single-AZ, storage excluded. Multi-AZ roughly doubles the instance charge. Check the AWS pricing page for current rates.

Ways to cut spend

Use Graviton instance families (t4g, m7g, r7g) for better price-performance.
Buy Reserved Instances for steady 1 to 3 year workloads.
Right-size from CloudWatch metrics rather than from the tier default.
Consider Aurora Serverless v2 for spiky or intermittent traffic.
Start allocatedStorage small and let autoscaling raise it, rather than over-provisioning.
Switch databaseInsights to false on non-production instances that nobody inspects.

Best practices

Keep Multi-AZ on for production, which is the default.
Use memory-optimised types (r7g) for production write workloads.
Grant network access with allowDefaultPortFrom, not a hardcoded port.
Read credentials from the generated secret, never from a checked-in value.
Use grantIamConnect for application roles so no long-lived password is needed.
Test a restore before you rely on backups.
Wire alertsTopic so alarm notifications reach a real inbox.

Limitations

securityGroupIds and clusterIdentifier are accepted but ignored.
The read replica inherits almost everything from the primary. Only instanceType and availabilityZone are configurable.
RDS Proxy cannot listen on a custom port, so it always uses the engine default.
Deletion protection is on by default, so a stack destroy needs it turned off first.
The removal policy takes a final snapshot, so destroying a stack leaves a snapshot (and its CMK, when one was requested) behind.
Cross-region failover is not automatic. Use Global Aurora for that.
Read replicas lag the primary because replication is asynchronous.
Maintenance windows cause brief downtime on single-AZ instances.

Next Steps

Database Factory

Provision databases through the Fjall factory API.

RDS Aurora

Scale to an Aurora cluster with serverless and global options.

RDS Free Tier

Run a free-tier-eligible PostgreSQL instance during your first 12 months.

Secrets Manager

Manage database credentials and rotation.

​Overview

​Add a database from the CLI

​Import the construct

​Basic usage

​Configuration options

​Core properties

​Instance sizing

​Backup and maintenance

​Security

​Snapshot restore

​Optional features

​Ports and connectivity

​Security

​Encryption

​IAM database authentication

​Credentials

​Network placement

​High availability

​RDS Proxy

​Read replicas

​Database Insights

​Backups and restore

​Restoring from a snapshot

​Methods

​Complete example

​Cost optimisation

​Instance sizing

​Ways to cut spend

​Best practices

​Limitations

​Next Steps

Database Factory

RDS Aurora

RDS Free Tier

Secrets Manager

Overview

Add a database from the CLI

Import the construct

Basic usage

Configuration options

Core properties

Instance sizing

Backup and maintenance

Security

Snapshot restore

Optional features

Ports and connectivity

Security

Encryption

IAM database authentication

Credentials

Network placement

High availability

RDS Proxy

Read replicas

Database Insights

Backups and restore

Restoring from a snapshot

Methods

Complete example

Cost optimisation

Instance sizing

Ways to cut spend

Best practices

Limitations

Next Steps