Fjall Docs — deploy AWS infrastructure into your own account

Overview

DynamoDBTable creates an Amazon DynamoDB table with defaults tuned for serverless workloads: on-demand billing, point-in-time recovery on, and an AWS-managed KMS key. It also supports provisioned capacity, global secondary indexes, streams, and TTL expiry. Point-in-time recovery defaults to true and removalPolicy defaults to RETAIN, so a stack deletion leaves the table and its backups in place.

DynamoDB is not a fjall add database --type option. --type accepts Aurora, Instance, GlobalAurora and ClickHouse only. Declare a DynamoDB table by editing your application’s infrastructure.ts directly.

Add a table

Use DatabaseFactory and register the result with app.addDatabase(). The factory returns a DynamoDBDatabase wrapper that plugs into connections: on your compute resources.

import { DatabaseFactory } from "@fjall/components-infrastructure/lib/patterns/aws/database";

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

To place a table outside an application scope, instantiate the construct directly:

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

const table = new DynamoDBTable(scope, "Sessions", {
  partitionKey: { name: "sessionId", type: "S" },
});

Properties

Both DatabaseFactory.build("Id", { type: "DynamoDB", ... }) and new DynamoDBTable(scope, "Id", ...) accept the same properties, with one exception noted below.

Property	Type	Default	Description
`partitionKey`	`{ name: string, type: "S" \| "N" \| "B" }`	Required	Partition key attribute
`sortKey`	`{ name: string, type: "S" \| "N" \| "B" }`	-	Sort key attribute
`billingMode`	`"PAY_PER_REQUEST" \| "PROVISIONED"`	`"PAY_PER_REQUEST"`	Billing mode
`readCapacity`	`number`	-	Read capacity units (provisioned only)
`writeCapacity`	`number`	-	Write capacity units (provisioned only)
`globalSecondaryIndexes`	`DynamoDBGlobalSecondaryIndex[]`	-	GSI definitions
`timeToLiveAttribute`	`string`	-	TTL attribute name
`stream`	`"NEW_IMAGE" \| "OLD_IMAGE" \| "NEW_AND_OLD_IMAGES" \| "KEYS_ONLY"`	-	DynamoDB Streams view type
`pointInTimeRecovery`	`boolean`	`true`	Enable point-in-time recovery
`encryption`	`"AWS_OWNED" \| "AWS_MANAGED" \| "CUSTOMER_MANAGED"`	`"AWS_MANAGED"`	Encryption type
`deletionProtection`	`boolean`	`false`	Block table deletion in the AWS API
`removalPolicy`	`"DESTROY" \| "RETAIN" \| "SNAPSHOT"`	`"RETAIN"`	What happens on stack deletion
`tableName`	`string`	Generated	Physical table name (construct only)

tableName exists on DynamoDBTableProps but not on the factory’s DynamoDBDatabaseProps. Factory-built tables always take a CloudFormation-generated name.

deletionProtection and removalPolicy are independent. removalPolicy decides what CloudFormation does when the stack is deleted. deletionProtection blocks any DeleteTable call, including one issued outside CloudFormation.

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).

Key types

Type	DynamoDB type	Use for
`"S"`	String	IDs, names, emails
`"N"`	Number	Timestamps, counters
`"B"`	Binary	Hashes, compressed data

Global secondary index fields

Field	Type	Default	Description
`indexName`	`string`	Required	Index name
`partitionKey`	`{ name, type }`	Required	Index partition key
`sortKey`	`{ name, type }`	-	Index sort key
`projectionType`	`"ALL" \| "KEYS_ONLY" \| "INCLUDE"`	`"ALL"`	Attributes projected into the index
`nonKeyAttributes`	`string[]`	-	Projected attributes for `"INCLUDE"`

Methods

The factory and the construct expose different method names. Pick the table that matches how you built the resource.

`DynamoDBDatabase` (returned by `DatabaseFactory`)

Method	Returns	Description
`getTableName()`	`string`	Table name
`getTableArn()`	`string`	Table ARN
`getStreamArn()`	`string \| undefined`	Stream ARN when streams are enabled
`getTable()`	`ITable`	Underlying CDK Table construct
`grantReadData(grantee)`	`Grant`	Grant read access
`grantWriteData(grantee)`	`Grant`	Grant write access
`grantReadWriteData(grantee)`	`Grant`	Grant read and write access
`grantFullAccess(grantee)`	`Grant`	Grant full access, including admin
`grantStreamRead(grantee)`	`Grant`	Grant stream read access

`DynamoDBTable` (the construct)

Method	Returns	Description
`getTableName()`	`string`	Table name
`getTableArn()`	`string`	Table ARN
`getTableStreamArn()`	`string \| undefined`	Stream ARN when streams are enabled
`getTable()`	`ITable`	Underlying CDK Table construct
`grantRead(grantee)`	`Grant`	Grant read access
`grantWrite(grantee)`	`Grant`	Grant write access
`grantReadWrite(grantee)`	`Grant`	Grant read and write access
`grantFullAccess(grantee)`	`Grant`	Grant full access, including admin
`grantStreamRead(grantee)`	`Grant`	Grant stream read access

Examples

Composite key table

const orders = app.addDatabase(
  DatabaseFactory.build("Orders", {
    type: "DynamoDB",
    partitionKey: { name: "customerId", type: "S" },
    sortKey: { name: "orderDate", type: "N" },
  }),
);

Table with a global secondary index

const users = app.addDatabase(
  DatabaseFactory.build("Users", {
    type: "DynamoDB",
    partitionKey: { name: "userId", type: "S" },
    globalSecondaryIndexes: [
      {
        indexName: "emailIndex",
        partitionKey: { name: "email", type: "S" },
        projectionType: "ALL",
      },
    ],
  }),
);

Give each GSI a key schema that differs from the table’s. Fjall logs a synth-time warning for a GSI that repeats the table’s partition and sort keys, because it costs storage and writes without adding a query path.

Provisioned throughput

const events = app.addDatabase(
  DatabaseFactory.build("Events", {
    type: "DynamoDB",
    partitionKey: { name: "pk", type: "S" },
    sortKey: { name: "sk", type: "S" },
    billingMode: "PROVISIONED",
    readCapacity: 100,
    writeCapacity: 50,
  }),
);

readCapacity and writeCapacity apply only when billingMode is "PROVISIONED". Setting them under on-demand billing logs a warning at synth and the values are dropped. Setting "PROVISIONED" without them logs a warning and falls back to CDK defaults.

Streams into Lambda

addDynamoDbEventSource() lives on the LambdaFunction construct, so reach it with getLambdaFunction(). It takes a CDK ITable, so pass getTable() rather than the Fjall wrapper.

import { ComputeFactory } from "@fjall/components-infrastructure";
import { Code } from "aws-cdk-lib/aws-lambda";

const audit = app.addDatabase(
  DatabaseFactory.build("AuditLog", {
    type: "DynamoDB",
    partitionKey: { name: "entityId", type: "S" },
    sortKey: { name: "timestamp", type: "N" },
    stream: "NEW_AND_OLD_IMAGES",
  }),
);

const processor = app.addCompute(
  ComputeFactory.build("StreamProcessor", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("./dist/stream-processor"),
    handler: "index.handler",
  }),
);

processor.getLambdaFunction().addDynamoDbEventSource(audit.getTable(), {
  batchSize: 100,
  startingPosition: "LATEST",
});

TTL for automatic expiry

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

Write expiresAt as a Unix epoch in seconds. DynamoDB deletes expired items within 48 hours at no cost.

Connecting to compute

List the table in connections: on a Lambda function or an ECS service. Fjall grants the table’s IAM actions to the ECS task role or the Lambda execution role. DynamoDB has no network primitive, so no security group rule is added.

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

app.addCompute(
  ComputeFactory.build("Api", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        connections: [sessions],
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

Connections default to readWrite. Narrow the grant with an access level of read, write or readWrite:

connections: [{ resource: sessions, access: "read" }];

A service that runs migrations: also receives DYNAMODB_TABLE_NAME and AWS_REGION in the migration task environment, plus a CRUD policy covering the table and its indexes.

Listing anything in connections puts the compute in the application VPC. ComputeFactory.build treats a non-empty connections array as a VPC requirement and passes app.getVpc() in, so a Lambda that only talks to DynamoDB still gets ENIs in private subnets and pays for the NAT gateway or interface endpoints that reach the DynamoDB API. DynamoDB itself needs no VPC. To keep a function out of the VPC, leave connections off and grant it directly with grantReadData / grantReadWriteData.

For a grantee you hold directly, call the grant methods:

sessions.grantReadData(readerLambda);
sessions.grantReadWriteData(writerLambda);

grantStreamRead() requires stream to be set on the table. Calling it on a table without streams fails at synth.

CloudFormation outputs

Each table exports the following, where {id} is the construct id you passed:

Output	Condition	Description
`{id}TableName`	Always	Table name
`{id}TableArn`	Always	Table ARN
`{id}TableStreamArn`	Only when `stream` is set	Stream ARN

Next Steps

Database Factory

Compare DynamoDB against Aurora, RDS and ClickHouse

Lambda Function

Process DynamoDB streams with Lambda

Compute Factory

Wire tables into ECS services and Lambda functions

RDS Aurora

Use a relational store for joins and transactions

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

DynamoDB Table

Overview

Add a table

Properties

Key types

Global secondary index fields

Methods

`DynamoDBDatabase` (returned by `DatabaseFactory`)

`DynamoDBTable` (the construct)

Examples

Composite key table

Table with a global secondary index

Provisioned throughput

Streams into Lambda

TTL for automatic expiry

Connecting to compute

CloudFormation outputs

Next Steps

Database Factory

Lambda Function

Compute Factory

RDS Aurora

​Overview

​Add a table

​Properties

​Key types

​Global secondary index fields

​Methods

​DynamoDBDatabase (returned by DatabaseFactory)

​DynamoDBTable (the construct)

​Examples

​Composite key table

​Table with a global secondary index

​Provisioned throughput

​Streams into Lambda

​TTL for automatic expiry

​Connecting to compute

​CloudFormation outputs

​Next Steps

Database Factory

Lambda Function

Compute Factory

RDS Aurora

Overview

Add a table

Properties

Key types

Global secondary index fields

Methods

`DynamoDBDatabase` (returned by `DatabaseFactory`)

`DynamoDBTable` (the construct)

Examples

Composite key table

Table with a global secondary index

Provisioned throughput

Streams into Lambda

TTL for automatic expiry

Connecting to compute

CloudFormation outputs

Next Steps