DynamoDBBuilder

Purpose

The DynamoDBBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create AWS DynamoDB tables following organizational security and operational standards. This builder creates NoSQL database tables with configurable key schemas, Global Secondary Indexes (GSI), DynamoDB Streams for change data capture, pay-per-request billing for cost optimization, and automatic Parameter Store integration for cross-stack references.

Dependencies

This builder requires the following AWS resources and permissions:

Required AWS Permissions

• DynamoDB: Table creation, index management, and stream configuration
• Parameter Store: Write access for storing table and stream ARNs
• Resource Tagging: Permissions to apply organizational tags
• CloudFormation: Stack management and resource lifecycle operations

Foundation Dependencies

• Environment Configuration: Account and region mappings for multi-environment deployments
• Naming Standards: Organizational resource naming conventions
• Tagging Strategy: Consistent tagging for cost allocation and backup policies
• Cross-Stack Integration: Parameter Store for sharing table references

Configuration

The builder uses the DynamoDBConfig model for the validation of your configuration and becomes the authoritative source of all the dynamodb table settings.

CDK Configuration Structure

{
  "table_name": {
    "pk": {
      "name": "user_id",
      "type": "STRING"
    },
    "sk": {
      "name": "session_id",
      "type": "STRING"
    },
    "enable_stream": true,
    "indexes": {
      "status-index": {
        "pk": {
          "name": "status",
          "type": "STRING"
        },
        "sk": {
          "name": "expires_at",
          "type": "NUMBER"
        }
      }
    }
  }
}

Configuration Parameters

Parameter	Mandatory	Type	Default	Description
	Yes	str		Base name for table
pk	Yes	PartitionKey		Partition key configuration with name and type
sk	No	SortKey	None	Sort key configuration for composite primary keys
enable_stream	No	bool	false	Enable DynamoDB Streams with NEW_AND_OLD_IMAGES view
indexes	No	Dict[str, GlobalSecondaryIndex]	None	Global Secondary Index configurations
tag_key	Yes	str		Primary tag key for backup and operational policies
tag_value	Yes	str		Primary tag value for backup and operational policies

Please check the following models to have a detailed view on the configuration of the pk, skand indexes:

• PartitionKey model
• SortKey model
• GlobalSecondaryIndex model

Usage

Here’s an example of how to use the DynamoDBBuilder to build a DynamoDB table in a CDK stack:

table_config = app_helper.get_from_env("table_name")

dynamodb_builder = DynamoDBBuilder()
table = dynamodb_builder.set_application_helper(app_helper) \
                        .set_builder_config(table_config) \
                        .set_table_base_name("table_name") \
                        .build(scope_from_stack)

Behavior and Features

Automatic Table Configuration

Billing and Performance:

• Pay-per-Request Billing: Automatic scaling without capacity planning
• Global Secondary Indexes: All indexes use ALL projection type for maximum query flexibility
• Performance Optimization: Efficient key design validation prevents hot partitions

Streaming Configuration:

• View Type: NEW_AND_OLD_IMAGES provides complete change records
• Integration Ready: Stream ARN automatically stored in Parameter Store
• Cost Awareness: Streaming only enabled when explicitly configured

Data Retention and Lifecycle:

• Retention Policy: RETAIN removal policy prevents accidental data loss
• Manual Cleanup: Tables must be manually deleted for safety
• Backup Integration: Configurable tagging for automated backup policies

Naming Convention

Table names follow the pattern: {organization-prefix}-{app-name}-{table-base-name}

The builder automatically:

• Applies organizational naming standards
• Converts names to lowercase with hyphens
• Truncates names to respect DynamoDB limits (255 characters)
• Ensures name uniqueness within the account and region

Parameter Store Integration

Each table automatically creates Parameter Store entries for cross-stack references:

• Table ARN: DYNAMODB_TABLE_{TABLE_NAME_UPPER_SNAKE_CASE}
• Stream ARN: DYNAMODB_TABLE_STREAM_{TABLE_NAME_UPPER_SNAKE_CASE} (when streaming is enabled)

Key Schema and Index Design

Primary Key Patterns:

• Partition Key Only: Simple key-value lookups
• Composite Primary Key: Partition key + sort key for hierarchical data
• Attribute Types: STRING, NUMBER, and BINARY supported

Global Secondary Index Features:

• Independent Key Schema: Different partition/sort keys from main table
• Full Projection: ALL attributes projected for maximum query flexibility
• Automatic Naming: Index names follow {config-key}-index pattern
• Pay-per-Request: Same billing model as main table

Streaming and Change Data Capture

Stream Configuration:

• View Type: NEW_AND_OLD_IMAGES captures complete change records
• Retention: 24-hour stream record retention

Security Features

Access Control:

• IAM Integration: Fine-grained permissions through IAM policies
• Resource-Based Policies: Table-level access control
• Cross-Account Access: Controlled sharing between AWS accounts

Compliance Features:

• Audit Trails: All access logged through CloudTrail
• Vulnerability Scanning: CVE detection on image push
• Tag-Based Security: Organizational tags for compliance tracking

Notes

• The set_usage method from the abstract class should not be used in this builder.
• The table_name parameter of the set_table_base_name method should be extracted from the cdk.json config key.
• DynamoDB table names are case-sensitive and must be unique within account/region
• Pay-per-request billing is always used (no provisioned capacity options)