Fjall Docs — deploy AWS infrastructure into your own account

Overview

DatabaseFactory builds database resources from a type-safe props object. Each type is a separate overload, so TypeScript narrows the available options as soon as you set type.

For S3 storage buckets, use the StorageFactory instead.

Basic Usage

import { App, DatabaseFactory } from "@fjall/components-infrastructure";

const app = App.getApp("api");

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
  }),
);

Database Types

Type	Resource	Returns
`Aurora`	Aurora Serverless v2 cluster	`RelationalDatabase`
`Instance`	RDS database instance	`RelationalDatabase`
`GlobalAurora`	Aurora global cluster (multi-region)	`RelationalDatabase`
`DynamoDB`	DynamoDB table	`DynamoDBDatabase`
`ClickHouse`	Single-node ClickHouse on EC2 + ECS	`ClickHouseDatabase`

Aurora

Aurora Serverless v2 cluster running PostgreSQL or MySQL:

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
    databaseEngine: "postgresql", // or "mysql"
  }),
);

Behaviour:

Serverless v2 writer plus one reader by default. Set readers: false for a single-instance cluster.
Storage encrypted at rest, SSL enforced through the parameter group.
Deletion protection on, and the removal policy defaults to SNAPSHOT.
Enhanced Monitoring on at a one-minute interval, and Database Insights on in standard mode.

RDS Instance

A single database instance for predictable workloads:

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Instance",
    databaseName: "orders",
    databaseEngine: "postgresql",
    instanceType: "t4g.micro",
  }),
);

Behaviour:

Fixed instance size, with storage autoscaling to 500 GiB.
Multi-AZ on by default. Pass multiAz: false for a single-AZ instance.
IAM database authentication on by default, alongside password auth.
t4g.micro is free-tier eligible.

Global Aurora

Multi-region Aurora cluster:

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "GlobalAurora",
    databaseName: "orders",
    primaryRegion: "us-east-1",
    secondaryRegions: ["eu-west-1", "ap-southeast-2"],
  }),
);

Behaviour:

Cross-region replication with low-latency reads in each secondary region.
Managed failover to a secondary region.
primaryRegion is required. Synth fails without it.

DynamoDB

Serverless key-value and document store:

const sessions = app.addDatabase(
  DatabaseFactory.build("Sessions", {
    type: "DynamoDB",
    partitionKey: { name: "sessionId", type: "S" },
    sortKey: { name: "createdAt", type: "N" },
  }),
);

Behaviour:

On-demand billing by default (PAY_PER_REQUEST).
Point-in-time recovery on by default.
Encrypted with the AWS-managed aws/dynamodb KMS key by default, which bills KMS API requests.

The factory does not configure DynamoDB global tables. For a multi-region relational store, use GlobalAurora.

ClickHouse

Single-node ClickHouse analytics database on EC2 with an ECS task, an EBS data volume and an S3 cold tier:

const analytics = app.addDatabase(
  DatabaseFactory.build("Analytics", {
    type: "ClickHouse",
    schemaAdmin: { name: "schema_admin", profile: "ddl_admin" },
  }),
);

Behaviour:

Database name is fixed at analytics.
schemaAdmin is required. Its name must match ^[a-z][a-z0-9_]*$ and must not carry the reserved fjall prefix. Its profile names a key in profiles, or one of the four defaults: high_throughput_ingest, audit_append, read_only, ddl_admin.
Scheduled OPTIMIZE TABLE FINAL every 6 hours, plus a daily backup to S3 at 03:00 UTC that restores what it wrote into a scratch database to verify it.
storageGb grows only. EBS refuses to shrink a volume and permits one modification per volume per 6 hours.

Configuration Parameters

Defaults the backup tier owns

Four defaults on this page read the application’s backup tier (App.getApp(name, { backup: { tier } })) rather than a fixed value. An application with no backup tier, or backup: false, gets the Standard column. Setting the parameter on the resource overrides the tier for that resource.

Parameter	Standard, or no tier	Resilient	Enterprise
`backupRetention` (Aurora, Instance, GlobalAurora)	14 days	30 days	35 days
`databaseInsights.mode`	`"standard"`	`"standard"`	`"advanced"`
DynamoDB `deletionProtection`	`false`	`true`	`true`
DynamoDB `encryption`	`"AWS_MANAGED"`	`"AWS_MANAGED"`	`"CUSTOMER_MANAGED"`, one key per stack

fjall destroy switches deletion protection off on every database, table and load balancer in a stack before deleting it, so a protected table never wedges a destroy; it only stops a delete that nobody asked for.

Shared (Aurora, Instance, GlobalAurora)

Parameter	Type	Description	Default
`type`	`"Aurora" \| "Instance" \| "GlobalAurora"`	Database type	Required
`databaseName`	`string`	Logical database name	Required
`databaseEngine`	`"postgresql" \| "mysql"`	Engine family	`"postgresql"`
`engine`	`IClusterEngine \| IInstanceEngine`	CDK engine object. Overrides `databaseEngine`	-
`port`	`number`	Database port	5432 / 3306
`deletionProtection`	`boolean`	Block stack-driven deletion	`true`
`backupRetention`	`number`	Automated backup retention, in days	Backup tier
`databaseInsights`	`DatabaseInsightsConfig \| false`	Database Insights config, or `false` to disable	On, tier mode
`credentials`	`CredentialsConfig`	Master username and opt-in secret rotation	Auto
`proxy`	`ProxyConfig \| false`	RDS Proxy configuration	Off
`migrations`	`MigrationsConfig`	Schema-version gate for connected services	-
`alertsTopic`	`ITopic \| string`	SNS topic for alarm notifications	-
`alarms`	`RdsAlarmThresholds \| false`	Alarm thresholds, or `false` to disable	Defaults
`snapshotIdentifier`	`string`	Restore from an existing snapshot	-
`snapshotUsername`	`string`	Master username inside the snapshot	-
`vpc`	`IVpc`	VPC override	`app.getVpc()`

When a proxy fronts the database, clients connect on the engine-default port even if you set a custom port. RDS Proxy has no port parameter.

DatabaseInsightsConfig takes two fields:

Field	Type	Description	Default
`mode`	`"standard" \| "advanced"`	`standard` retains 7 days, `advanced` retains 15 months	`"standard"`
`encryptionKey`	`EncryptionKeySpec`	KMS key for the Insights data	Default key

CredentialsConfig takes username and an opt-in secretRotation block. Rotation resources are created only when you pass an object. secretRotation: { automaticallyAfterDays: 30 } is the scaffolded form.

Cluster (Aurora and Global Aurora)

Parameter	Type	Description	Default
`writer`	`AuroraWriterConfig`	Writer instance configuration	Auto
`readers`	`AuroraReadersConfig \| false`	Reader configuration, or `false` for no readers	One reader
`encryption`	`AuroraEncryptionConfig`	Storage encryption key	Default key
`monitoringInterval`	`Duration`	Enhanced Monitoring interval, billable	`Duration.minutes(1)`
`preferredMaintenanceWindow`	`string`	Maintenance window	`"Sat:12:30-Sat:20:30"`

AuroraReadersConfig takes count (default 1), or a per-reader instances array, plus defaultEnableDatabaseInsights. count and instances are mutually exclusive.

Aurora only

Parameter	Type	Description	Default
`removalPolicy`	`RemovalPolicy`	What happens to the cluster on stack deletion	`RemovalPolicy.SNAPSHOT`
`serverlessV2MinCapacity`	`number`	Serverless v2 floor in ACU. `0` scales to zero	CDK default
`serverlessV2MaxCapacity`	`number`	Serverless v2 ceiling in ACU	CDK default
`serverlessV2AutoPauseDuration`	`Duration`	Idle time before auto-pause. 5 minutes to 24 hours	-
`enableDataApi`	`boolean`	RDS Data API HTTP endpoint	`false`
`engineVersion`	`string`	Aurora PostgreSQL version, for example `"16.10"`	Engine default
`clusterIdentifier`	`string`	Physical cluster identifier	Derived
`credentialsSecretName`	`string`	Physical name of the master-credentials secret	Derived
`publiclyAccessible`	`boolean`	Place the cluster in public subnets	`false`
`allowedIpCidr`	`string`	IPv4 CIDR allowed in when public	-
`allowVpcAccess`	`boolean`	Allow the whole VPC CIDR in	`false`

removalPolicy: RemovalPolicy.DESTROY takes the data with it when the stack is deleted. No snapshot, no recovery. Reserve it for disposable dev clusters.

serverlessV2MinCapacity: 0 requires Aurora PostgreSQL 16.3 or later. Synth fails on an older engineVersion.

Global Aurora only

Parameter	Type	Description	Default
`primaryRegion`	`string`	Region hosting the primary cluster	Required
`secondaryRegions`	`string[]`	Regions hosting read replicas	`[]`
`globalClusterIdentifier`	`string`	Physical global-cluster identifier	Derived
`enableGlobalWriteForwarding`	`boolean`	Forward secondary writes to the primary	`false`

Global Aurora does not accept removalPolicy, engineVersion, or the serverless v2 capacity props.

Instance

Parameter	Type	Description	Default
`instanceType`	`string`	Instance class	`"t4g.large"`
`allocatedStorage`	`number`	Storage in GiB. Autoscales to 500 GiB	`100`
`multiAz`	`boolean`	Standby in a second Availability Zone	`true`
`iamAuthentication`	`boolean`	RDS IAM database authentication	`true`
`readReplica`	`ReadReplicaConfig \| false`	Read replica configuration	Off
`encryption`	`EncryptionConfig`	Storage encryption key	Default
`publiclyAccessible`	`boolean`	Place the instance in public subnets	`false`

ReadReplicaConfig takes instanceType and availabilityZone. The replica inherits the primary’s instanceType when unset. monitoringInterval and preferredMaintenanceWindow are cluster-only props. Instance databases apply the same defaults but expose no override. Aurora and Global Aurora ignore instanceType because their instances are serverless v2.

Multi-AZ is on by default and bills for a standby. Pass multiAz: false for development instances.

DynamoDB

Parameter	Type	Description	Default
`partitionKey`	`{ name, type }`	Partition key definition	Required
`sortKey`	`{ name, type }`	Sort key definition	-
`billingMode`	`"PAY_PER_REQUEST" \| "PROVISIONED"`	Billing mode	`"PAY_PER_REQUEST"`
`readCapacity`	`number`	Read capacity units, provisioned only	-
`writeCapacity`	`number`	Write capacity units, provisioned only	-
`globalSecondaryIndexes`	`DynamoDBGlobalSecondaryIndex[]`	GSI definitions	-
`timeToLiveAttribute`	`string`	TTL attribute name	-
`pointInTimeRecovery`	`boolean`	Enable PITR	`true`
`stream`	`"NEW_IMAGE" \| "OLD_IMAGE" \| "NEW_AND_OLD_IMAGES" \| "KEYS_ONLY"`	DynamoDB Streams view type	-
`encryption`	`"AWS_OWNED" \| "AWS_MANAGED" \| "CUSTOMER_MANAGED"`	Table encryption mode	Backup tier
`deletionProtection`	`boolean`	Block table deletion	Backup tier
`removalPolicy`	`"DESTROY" \| "RETAIN" \| "SNAPSHOT"`	What happens on stack deletion	`"RETAIN"`

Attribute types are "S" (string), "N" (number) and "B" (binary). encryption and deletionProtection follow the backup tier unless set here.

AWS_MANAGED encrypts with the AWS-managed aws/dynamodb KMS key and bills KMS API requests. AWS_OWNED uses an AWS-owned key at no cost. CUSTOMER_MANAGED encrypts with the stack’s shared customer-managed key (one key per stack, created on first use, about $1–3 a month).

ClickHouse

Parameter	Type	Description	Default
`schemaAdmin`	`{ name, profile }`	Bootstrap-privileged user that runs customer SQL	Required
`instanceType`	`string`	EC2 instance type	`"m7g.medium"`
`storageGb`	`number`	EBS data-volume size in GiB. Growth only	`400`
`iops`	`number`	Provisioned IOPS on the gp3 volume	`3000`
`throughputMbps`	`number`	Provisioned throughput in MiB/s	`125`
`coldTier`	`false \| { mode: "s3" }`	S3 cold tier, or `false` for hot storage only. The cold-tier bucket is unversioned by design and carries the `fjall:s3:versioning-exempt` tag valued `cold-tier`	Enabled
`optimiseSchedule`	`string \| false`	`OPTIMIZE TABLE FINAL` schedule	`"rate(6 hours)"`
`backupSchedule`	`string \| false`	Backup-to-S3 schedule	`"cron(0 3 * * ? *)"`
`backupVerify`	`false`	Disable the restore-verify pass	Verify on
`backupRetentionDays`	`number`	Backup retention in days	`14`
`managedPasswords`	`string[]`	Workload users the framework mints secrets for	`[]`
`profiles`	`Record<string, ProfileSpec>`	Per-profile resource caps. Replaces the defaults	Derived from instance
`migrations`	`{ dir, versionResolver? }`	ClickHouse schema-version gate	-
`tls`	`ClickHouseTlsOptions`	TLS configuration	-
`alertsTopic`	`ITopic \| string`	SNS topic for alarm notifications	-
`alarms`	`ClickHouseAlarmThresholds \| false`	Alarm thresholds	Defaults

Changing instanceType or storageGb versions the launch template and triggers an ASG instance refresh. On a single-node cluster that refresh is a restart: data survives, the cluster is unavailable across the window.

Common Patterns

Production Aurora

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
    databaseEngine: "postgresql",
    databaseInsights: { mode: "advanced" },
    backupRetention: 35,
  }),
);

Development Database

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Instance",
    databaseName: "orders_dev",
    instanceType: "t4g.micro", // Free tier eligible
    multiAz: false,
    deletionProtection: false,
  }),
);

Single-Instance Aurora

Drop the default reader when one writer is enough:

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
    readers: false,
  }),
);

Scale-to-Zero Aurora

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

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
    engineVersion: "16.10",
    serverlessV2MinCapacity: 0,
    serverlessV2MaxCapacity: 4,
    serverlessV2AutoPauseDuration: Duration.minutes(20),
    enableDataApi: true,
  }),
);

Session Store

const sessions = app.addDatabase(
  DatabaseFactory.build("Sessions", {
    type: "DynamoDB",
    partitionKey: { name: "sessionId", type: "S" },
    timeToLiveAttribute: "expiresAt",
    encryption: "AWS_OWNED",
  }),
);

Accessing Database Information

Relational Databases

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
  }),
);

const host = orders.getHostEndpoint();
const port = orders.getHostPort();
const name = orders.getDatabaseName();

// Connection string without credentials
const base = orders.getConnectionString();

// Credentials secret (Fjall Secret wrapper)
const credentials = orders.getCredentials();

getConnectionString() returns <scheme>://<host>:<port>/<dbname> and deliberately excludes credentials. Secrets Manager references cannot be interpolated at synth time without baking plaintext into the CloudFormation template. Compose the final URL at runtime from the injected user and password.

DynamoDB

const sessions = app.addDatabase(
  DatabaseFactory.build("Sessions", {
    type: "DynamoDB",
    partitionKey: { name: "sessionId", type: "S" },
  }),
);

const tableName = sessions.getTableName();
const tableArn = sessions.getTableArn();

ClickHouse

const analytics = app.addDatabase(
  DatabaseFactory.build("Analytics", {
    type: "ClickHouse",
    schemaAdmin: { name: "schema_admin", profile: "ddl_admin" },
    managedPasswords: ["ingest"],
  }),
);

const url = analytics.getUrl(); // HTTP interface
const nativeUrl = analytics.getNativeUrl();
const ingest = analytics.getUser("ingest"); // Secret for that user

Connecting to Compute

Lambda

connections sits at the root of the Lambda props. The factory injects the application VPC automatically when connections are present.

import { Code, ComputeFactory } from "@fjall/components-infrastructure";

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", { type: "Aurora", databaseName: "orders" }),
);

app.addCompute(
  ComputeFactory.build("Api", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("./dist"),
    handler: "api.handler",
    connections: [orders],
  }),
);

ECS

connections sits on each service inside services[], not at the compute root. Each service gets its own least-privilege grants.

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", { type: "Aurora", databaseName: "orders" }),
);

app.addCompute(
  ComputeFactory.build("Api", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        connections: [orders],
        containers: [
          {
            port: 3000,
            environment: {
              DATABASE_URL_BASE: orders.getConnectionString(),
            },
            secretsImport: {
              DATABASE_USER: orders.getCredentials().getImport("username"),
              DATABASE_PASSWORD: orders.getCredentials().getImport("password"),
            },
          },
        ],
      },
    ],
  }),
);

Granting Access

Relational Databases

connections handles security groups and IAM grants. For a manual grant:

orders.grantConnect(lambdaFunction);

grantIamConnect issues short-lived rds-db:connect tokens for a named database user, so the grantee never reads a stored password. It is Instance-only and throws at synth on Aurora or Global Aurora:

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", { type: "Instance", databaseName: "orders" }),
);

orders.grantIamConnect(lambdaFunction, "app_user");

DynamoDB

sessions.grantReadData(lambdaFunction);
sessions.grantWriteData(lambdaFunction);
sessions.grantReadWriteData(lambdaFunction);
sessions.grantFullAccess(lambdaFunction);
sessions.grantStreamRead(lambdaFunction);

Schema Migrations

A migrations block turns the database into a schema-version gate. Every container of every service whose connections include the database receives EXPECTED_SCHEMA_VERSION at synth time, and eligible services gain a fjall-schema-gate container that verifies the live schema before any application container starts.

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "Aurora",
    databaseName: "orders",
    migrations: { tool: "prisma", dir: "./prisma/migrations" },
  }),
);

tool: "custom" takes the same dir plus a versionResolver: (dir: string) => string. ClickHouse uses its own block with dir and an optional versionResolver, and no tool field. See Deployment safety for the full gate behaviour.

Security

Every database the factory builds arrives with:

Encryption at rest. Storage encryption on for relational types, KMS encryption for DynamoDB tables.
Encryption in transit. rds.force_ssl=1 for PostgreSQL, require_secure_transport=ON for MySQL.
Secrets Manager credentials. Master credentials generated into a secret, never rendered into the template.
VPC isolation. Private subnets unless publiclyAccessible is set.
Least-privilege security groups. Rules created per connected service, not per cluster.

Best Practices

Use Aurora for variable workloads, Instance for predictable small ones.
Set readers: false on non-production Aurora clusters to halve the instance bill.
Set multiAz: false and deletionProtection: false on development instances.
Set databaseInsights: { mode: "advanced" } in production for 15 months of query history.
Declare connections rather than hand-wiring security groups and IAM.
Declare migrations so a schema mismatch stops the deployment instead of crash-looping.

Next Steps

Aurora Reference

Aurora cluster options in depth

DynamoDB Reference

Table, index and stream configuration

Compute Factory

Deploy Lambda and ECS compute resources

Deployment Safety

Schema gates and destructive-change consent

​Overview

​Basic Usage

​Database Types

​Aurora

​RDS Instance

​Global Aurora

​DynamoDB

​ClickHouse

​Configuration Parameters

​Defaults the backup tier owns

​Shared (Aurora, Instance, GlobalAurora)

​Cluster (Aurora and Global Aurora)

​Aurora only

​Global Aurora only

​Instance

​DynamoDB

​ClickHouse

​Common Patterns

​Production Aurora

​Development Database

​Single-Instance Aurora

​Scale-to-Zero Aurora

​Session Store

​Accessing Database Information

​Relational Databases

​DynamoDB

​ClickHouse

​Connecting to Compute

​Lambda

​ECS

​Granting Access

​Relational Databases

​DynamoDB

​Schema Migrations

​Security

​Best Practices

​Next Steps

Aurora Reference

DynamoDB Reference

Compute Factory

Deployment Safety

Overview

Basic Usage

Database Types

Aurora

RDS Instance

Global Aurora

DynamoDB

ClickHouse

Configuration Parameters

Defaults the backup tier owns

Shared (Aurora, Instance, GlobalAurora)

Cluster (Aurora and Global Aurora)

Aurora only

Global Aurora only

Instance

DynamoDB

ClickHouse

Common Patterns

Production Aurora

Development Database

Single-Instance Aurora

Scale-to-Zero Aurora

Session Store

Accessing Database Information

Relational Databases

DynamoDB

ClickHouse

Connecting to Compute

Lambda

ECS

Granting Access

Relational Databases

DynamoDB

Schema Migrations

Security

Best Practices

Next Steps