Python DynamoDB

This generator creates a new Python project backed by Amazon DynamoDB, using PynamoDB for entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.

Usage

Generate a DynamoDB Project

Run this generator@aws/nx-plugin:py#dynamodb

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:py#dynamodb

$ yarn nx g @aws/nx-plugin:py#dynamodb

$ npx nx g @aws/nx-plugin:py#dynamodb

$ bunx nx g @aws/nx-plugin:py#dynamodb

Install the Nx Console VSCode Plugin if you haven't already
Open the Nx Console in VSCode
Click Generate (UI) in the "Common Nx Commands" section
Search for @aws/nx-plugin - py#dynamodb
Fill in the required parameters
Click Generate

Build your command8

nameRequired

Options

Generator Options8 options

nameRequiredstring: Name of the DynamoDB project to generate
directorystringDefault: packages: The directory to store the project in.
frameworkenumDefault: pynamodb: The framework to use for DynamoDB entities.
pynamodb
infraenumDefault: dynamodb: Infrastructure to provision for the DynamoDB table.
dynamodbnone
iacenumDefault: inherit: The preferred IaC provider. By default this is inherited from your initial selection.
inheritcdkterraform
subDirectorystring: The sub directory the project is placed in. By default this is the project name.
tableNamestring: The DynamoDB table name. Auto-generated if not specified.
preferInstallDependenciesbooleanDefault: true: Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator creates the following project structure in the <directory>/<name> directory:

Directory<name>
- __init__.py Package exports
- client.py DynamoDB client and table name resolution
- Directoryentities
  - base.py Base PynamoDB model with GSI declarations
  - example.py Example entity definition
  - __init__.py Entity exports
config.json Table configuration including GSI definitions and local development settings
project.json Project configuration and build targets

The local development scripts are shared across all DynamoDB projects (both TypeScript and Python) and generated once into:

Directorypackages/common/scripts/src/dynamodb
- create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
- pull-image.ts Pulls the DynamoDB Local image
- start-container.ts Starts the DynamoDB Local container

Infrastructure

Since this generator vends infrastructure as code based on your chosen iac, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ Constructs for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directorydynamodb
    <name>.ts Infrastructure specific to your table
- Directorycore
  - dynamodb.ts Generic DynamoDB table construct

Architecture

The deployed project provisions the table itself, which any project it is connected to reads and writes:

Loading the diagram…

Local Development

Starting Local DynamoDB

The generator configures a dev target that starts a DynamoDB Local instance and creates the table. Use the project’s dev target:

pnpm nx dev <project-name>

yarn nx dev <project-name>

npx nx dev <project-name>

bunx nx dev <project-name>

This automatically:

Pulls the DynamoDB Local image (pull-image target)
Starts a container
Creates a local table with the indexes defined in config.json

Data Modelling

The generated project uses PynamoDB for entity modelling. All entities must inherit from the generated BaseModel — it resolves the correct DynamoDB table name at runtime, reading from AWS AppConfig when deployed or from config.json when running locally via DynamoDB Local. Without this, PynamoDB will not know which table to use. BaseModel also uses PynamoDB’s polymorphism support to store multiple entity types in a single table, following DynamoDB’s single-table design.

Add or update entity files under <name>/entities/, using the generated example entity as a starting point:

from collections.abc import Iterator
from datetime import UTC, datetime
from pynamodb.attributes import UnicodeAttribute
from .base import BaseModel


class ExampleModel(BaseModel, discriminator='ExampleModel'):
    """
    Key design:
      pk=EXAMPLE#<id>,        sk=EXAMPLE#<id>
      gsi1pk=CATEGORY#<cat>,  gsi1sk=EXAMPLE#<id>    <- list items by category
      gsi2pk=EXAMPLE,         gsi2sk=<created_at>    <- list all items by date
    """

    name = UnicodeAttribute()
    category = UnicodeAttribute()
    created_at = UnicodeAttribute()
    updated_at = UnicodeAttribute()

    @classmethod
    def make_pk(cls, id: str) -> str:
        return f'EXAMPLE#{id}'

    @classmethod
    def create(cls, id: str, name: str, category: str) -> 'ExampleModel':
        now = datetime.now(UTC).isoformat()
        item = cls(
            pk=cls.make_pk(id),
            sk=cls.make_pk(id),
            gsi1pk=f'CATEGORY#{category}',
            gsi1sk=cls.make_pk(id),
            gsi2pk='EXAMPLE',
            gsi2sk=now,
            name=name,
            category=category,
            created_at=now,
            updated_at=now,
        )
        item.save()
        return item

    # ── Primary index ─────────────────────────────────────────────────────────
    @classmethod
    def get_by_id(cls, id: str) -> 'ExampleModel':
        return cls.get(cls.make_pk(id), cls.make_pk(id))

    # ── gsi1_index: partition=category, sort=id ───────────────────────────────
    @classmethod
    def list_by_category(cls, category: str) -> Iterator['ExampleModel']:
        return cls.gsi1_index.query(f'CATEGORY#{category}')

    # ── gsi2_index: partition=type, sort=created_at ───────────────────────────
    @classmethod
    def list_created_between(cls, start: datetime, end: datetime) -> Iterator['ExampleModel']:
        return cls.gsi2_index.query(
            'EXAMPLE',
            range_key_condition=ExampleModel.gsi2sk.between(
                start.isoformat(), end.isoformat(),
            ),
            scan_index_forward=False,
        )

For more details, see the PynamoDB tutorial.

Designing Around Access Patterns

In DynamoDB, schema design starts with your queries, not your data shape. Before writing any model, list every access pattern your application needs, then design pk, sk, and GSI key values so each pattern is answered by a single table request — no JOINs, no sequential reads.

The generated ExampleModel demonstrates this for three patterns:

Get by ID — primary index, pk=EXAMPLE#<id>, sk=EXAMPLE#<id>
List by category — gsi1, pk=CATEGORY#<category>
List by creation date — gsi2, pk=EXAMPLE, sort key between ISO timestamps

The type prefix convention (e.g. EXAMPLE#, CATEGORY#) is deliberate: it makes items self-describing when browsing the table, prevents accidental key collisions between entity types that share an index, and allows sort key prefix filtering using begins_with.

Before writing a new entity, define its key patterns upfront in a docstring. The OrderModel in the next section follows this convention:

class OrderModel(BaseModel, discriminator='OrderModel'):
    """
    Key design:
      pk=ORDER#<order_id>,    sk=ORDER#<order_id>
      gsi1pk=USER#<user_id>,  gsi1sk=ORDER#<order_id>   <- list orders for a user
      gsi2pk=ORDER,           gsi2sk=<created_at>        <- list all orders by date
    """

Storing Multiple Entity Types

PynamoDB’s DiscriminatorAttribute stores a type label (entity_type) in every item. When querying via BaseModel, this label is used to instantiate each result as its correct subclass automatically — so a single query can return a mix of UserModel, OrderModel, and any other entity type registered in the same table.

PynamoDB’s DiscriminatorAttribute was designed for class hierarchy polymorphism within a single homogeneous table — not for storing structurally different entity types in one table. The pattern used here works, but keep these caveats in mind:

Key collision is your responsibility. PynamoDB does not prevent two entity types from writing the same pk/sk pair. Always use unique type prefixes (e.g. ORDER#, USER#).
Cross-entity queries require BaseModel. PynamoDB automatically adds a discriminator filter when querying a specific subclass, so items of other entity types at the same key will never be returned. To retrieve a mix of types from a shared GSI partition key, always query via BaseModel.
Shared table settings. All entities share the Meta configuration (table name, region, credentials) defined in BaseModel.

Below is a complete two-entity example — a UserModel with associated OrderModel records stored in the same table:

from collections.abc import Iterator
from datetime import UTC, datetime
from pynamodb.attributes import UnicodeAttribute
from .base import BaseModel


class UserModel(BaseModel, discriminator='UserModel'):
    """
    Key design:
      pk=USER#<user_id>,  sk=USER#<user_id>
      gsi2pk=USER,        gsi2sk=<created_at>    <- list all users by date
    """

    username = UnicodeAttribute()
    email = UnicodeAttribute()
    created_at = UnicodeAttribute()

    @classmethod
    def make_pk(cls, user_id: str) -> str:
        return f'USER#{user_id}'

    @classmethod
    def create(cls, user_id: str, username: str, email: str) -> 'UserModel':
        now = datetime.now(UTC).isoformat()
        item = cls(
            pk=cls.make_pk(user_id),
            sk=cls.make_pk(user_id),
            gsi2pk='USER',
            gsi2sk=now,
            username=username,
            email=email,
            created_at=now,
        )
        item.save()
        return item

    @classmethod
    def get_by_id(cls, user_id: str) -> 'UserModel':
        return cls.get(cls.make_pk(user_id), cls.make_pk(user_id))

    @classmethod
    def list_recent(cls, limit: int | None = None) -> Iterator['UserModel']:
        return cls.gsi2_index.query('USER', limit=limit, scan_index_forward=False)

from collections.abc import Iterator
from datetime import UTC, datetime
from pynamodb.attributes import UnicodeAttribute
from .base import BaseModel


class OrderModel(BaseModel, discriminator='OrderModel'):
    """
    Key design:
      pk=ORDER#<order_id>,    sk=ORDER#<order_id>
      gsi1pk=USER#<user_id>,  gsi1sk=ORDER#<order_id>    <- list orders by user
      gsi2pk=ORDER,           gsi2sk=<created_at>         <- list all orders by date
    """

    user_id = UnicodeAttribute()
    total = UnicodeAttribute()
    created_at = UnicodeAttribute()

    @classmethod
    def make_pk(cls, order_id: str) -> str:
        return f'ORDER#{order_id}'

    @classmethod
    def create(cls, order_id: str, user_id: str, total: str) -> 'OrderModel':
        now = datetime.now(UTC).isoformat()
        item = cls(
            pk=cls.make_pk(order_id),
            sk=cls.make_pk(order_id),
            gsi1pk=f'USER#{user_id}',
            gsi1sk=cls.make_pk(order_id),
            gsi2pk='ORDER',
            gsi2sk=now,
            user_id=user_id,
            total=total,
            created_at=now,
        )
        item.save()
        return item

    @classmethod
    def get_by_id(cls, order_id: str) -> 'OrderModel':
        return cls.get(cls.make_pk(order_id), cls.make_pk(order_id))

    # ── gsi1_index: partition=user, sort=order_id ────────────────────────────
    @classmethod
    def list_by_user(cls, user_id: str) -> Iterator['OrderModel']:
        return cls.gsi1_index.query(f'USER#{user_id}')

    # ── gsi2_index: partition=type, sort=created_at ───────────────────────────
    @classmethod
    def list_recent(cls, limit: int | None = None) -> Iterator['OrderModel']:
        return cls.gsi2_index.query('ORDER', limit=limit, scan_index_forward=False)

Export the new entities from __init__.py:

from .user import UserModel
from .order import OrderModel
from .example import ExampleModel

GSI Overloading

BaseModel provides two shared GSIs (gsi1_index, gsi2_index). Both UserModel and OrderModel above write to gsi2 — but with different gsi2pk values (USER vs ORDER). This is GSI overloading: reusing a single physical index to serve multiple independent access patterns without consuming extra GSI capacity.

UserModel — gsi2pk=USER, gsi2sk=<created_at> → list all users by date
OrderModel — gsi2pk=ORDER, gsi2sk=<created_at> → list all orders by date

gsi1 can also be overloaded when multiple entity types share the same parent. If you later add a ReviewModel that also belongs to a user, you can assign it gsi1pk=USER#<user_id> with a REVIEW#<id> sort key — no additional GSI needed. Querying gsi1 via BaseModel then returns both orders and reviews for that user in one request, with PynamoDB instantiating each item as its correct subclass:

from .base import BaseModel
from .order import OrderModel
from .review import ReviewModel

user_id = 'user-123'
items = list(BaseModel.gsi1_index.query(f'USER#{user_id}'))

orders  = [i for i in items if isinstance(i, OrderModel)]
reviews = [i for i in items if isinstance(i, ReviewModel)]

To retrieve only one entity type from an overloaded GSI, use a sort key prefix condition:

orders_only = list(BaseModel.gsi1_index.query(
    f'USER#{user_id}',
    range_key_condition=BaseModel.gsi1sk.startswith('ORDER#'),
))

One-to-Many Relationships

In a one-to-many relationship the child entity stores a reference to its parent in a GSI partition key, making the relationship traversable in both directions without duplicating data. The UserModel / OrderModel example above is exactly this pattern:

Get a single order by ID — primary table: pk=ORDER#<id>, sk=ORDER#<id>
List all orders for a user — gsi1: pk=USER#<user_id>

An alternative to GSI-based lookups is the item collection pattern: give child items the same pk as their parent and use the sort key to differentiate them. This lets you retrieve the parent and all its children in a single primary-table query, without a GSI:

class OrderModel(BaseModel, discriminator='OrderModel'):
    """
    Key design (item collection):
      pk=USER#<user_id>,    sk=ORDER#<order_id>   <- co-located under the parent user
    """
    ...

# Retrieve the user and all their orders in one primary-table query
# BaseModel dispatches each item to its correct subclass via DiscriminatorAttribute
items = list(BaseModel.query(f'USER#{user_id}'))
user   = next(i for i in items if isinstance(i, UserModel))
orders = [i for i in items if isinstance(i, OrderModel)]

The tradeoff: item collections place all children under a single partition key, which is optimal for most workloads but can create a hot partition at extreme write throughput. The GSI approach (used in the examples above) keeps each entity in its own partition and is generally safer to start with.

Many-to-Many Relationships

Many-to-many relationships require a junction entity using the adjacency list pattern: a dedicated item that records each link, with its GSI key inverting the direction so the relationship can be traversed both ways.

Consider ArticleModel and TagModel, where an article can have many tags and a tag can apply to many articles:

from collections.abc import Iterator
from pynamodb.attributes import UnicodeAttribute
from .base import BaseModel


class ArticleTagModel(BaseModel, discriminator='ArticleTag'):
    """
    Junction entity for the Article ↔ Tag many-to-many relationship.

    Key design:
      pk=ARTICLE#<article_id>,  sk=TAG#<tag_name>             <- list tags for an article
      gsi1pk=TAG#<tag_name>,    gsi1sk=ARTICLE#<article_id>  <- list articles for a tag
    """

    article_id = UnicodeAttribute()
    tag_name = UnicodeAttribute()

    @classmethod
    def add(cls, article_id: str, tag_name: str) -> 'ArticleTagModel':
        item = cls(
            pk=f'ARTICLE#{article_id}',
            sk=f'TAG#{tag_name}',
            gsi1pk=f'TAG#{tag_name}',
            gsi1sk=f'ARTICLE#{article_id}',
            article_id=article_id,
            tag_name=tag_name,
        )
        item.save()
        return item

    @classmethod
    def remove(cls, article_id: str, tag_name: str) -> None:
        cls.get(f'ARTICLE#{article_id}', f'TAG#{tag_name}').delete()

    # ── Primary index: pk=article, sk=tag ─────────────────────────────────────
    @classmethod
    def list_tags_for_article(cls, article_id: str) -> Iterator['ArticleTagModel']:
        return cls.query(f'ARTICLE#{article_id}')

    # ── gsi1_index: pk=tag, sk=article ────────────────────────────────────────
    @classmethod
    def list_articles_for_tag(cls, tag_name: str) -> Iterator['ArticleTagModel']:
        return cls.gsi1_index.query(f'TAG#{tag_name}')

Because ArticleTagModel uses pk=ARTICLE#<article_id> — the same partition as the article itself — you can retrieve an article and all its tags in a single primary-table query:

from .base import BaseModel
from .article import ArticleModel
from .article_tag import ArticleTagModel

items   = list(BaseModel.query('ARTICLE#article-123'))
article = next(i for i in items if isinstance(i, ArticleModel))
tags    = [i.tag_name for i in items if isinstance(i, ArticleTagModel)]

For further reading on DynamoDB data modelling, see the DynamoDB data modelling guide and Creating a single-table design with Amazon DynamoDB.

Using the DynamoDB Client

The generated client.py exports two key utilities:

is_local() — returns True when LOCAL_DEV=true, used to switch between local and AWS behaviour.
get_table_name() — returns the DynamoDB table name. When LOCAL_DEV=true, reads the table name from localDev.tableName in config.json; otherwise fetches the name from AWS AppConfig using the RUNTIME_CONFIG_APP_ID environment variable and caches it for subsequent calls.

BaseModel in entities/base.py uses both to configure PynamoDB automatically:

Connection — BaseModel.Meta sets host from config.json and hardcodes region, aws_access_key_id, and aws_secret_access_key when is_local() is True, pointing PynamoDB at the local DynamoDB instance. In AWS, these are left unset so PynamoDB uses the default credential chain.
Table name — BaseModel._get_connection() calls get_table_name() before each operation, so the correct table is resolved at runtime without any manual configuration.

Stopping Local DynamoDB

Stopping dev (e.g. with Ctrl+C) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.

Due to limitations with signal handling on Windows, the container is not automatically removed when dev is stopped. You will need to remove it manually:

<engine> rm -f <scope>-dynamodb

Replace <engine> with your container engine (docker or finch) and <scope> with your Nx workspace scope (e.g. proj).

Adding/Removing Global Secondary Indexes

GSIs are defined in config.json at the project root under the tableConfig.globalSecondaryIndexes key. Add an entry for each GSI, then reflect the change in BaseModel by adding or removing the corresponding GlobalSecondaryIndex class and attributes in <name>/entities/base.py:

{
  ...
  "tableConfig": {
    "globalSecondaryIndexes": [
      {
        "indexName": "gsi1pk-gsi1sk-index",
        "partitionKey": "gsi1pk",
        "sortKey": "gsi1sk"
      },
      {
        "indexName": "gsi2pk-gsi2sk-index",
        "partitionKey": "gsi2pk",
        "sortKey": "gsi2sk"
      }
    ]
  }
}

The sortKey field is optional for hash-key-only GSIs.

This config file is the single source of truth read by all consumers:

Local development — dev reads config.json and creates or updates the local table to match the GSI list
CDK — the construct reads config.json at synth time, so GSI changes are reflected on the next cdk deploy
Terraform — the module reads config.json at plan/apply time

One GSI per Deployment

Connecting to the Table

In any Python project, add the DynamoDB package as a workspace dependency and import entity classes directly:

from my_db_package.entities import ExampleModel

item = ExampleModel.get_by_id('123')

Behind the scenes, ExampleModel calls get_table_name() to fetch the table name from AWS AppConfig at runtime.

Deploying your Table

The DynamoDB generator creates CDK or Terraform infrastructure based on your selected iac.

CDK
Terraform

The CDK construct is created in common/constructs. Example usage:

import { MyTable } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new MyTable(this, 'Table');
  }
}

This provisions a DynamoDB table with:

pk (partition key) and sk (sort key), both String type
Global Secondary Indexes as defined in config.json
On-demand (PAY_PER_REQUEST) billing
Customer-managed KMS encryption with automatic key rotation
Point-in-time recovery enabled
Deletion protection enabled
Table name registered in Runtime Config under the dynamodb namespace in AWS AppConfig

The Terraform module is created in common/terraform. Example usage:

module "my_table" {
  source = "../../common/terraform/src/app/dynamodb/my-table"
}

This provisions a DynamoDB table with:

pk (partition key) and sk (sort key), both String type
Global Secondary Indexes as defined in config.json
On-demand (PAY_PER_REQUEST) billing
Customer-managed KMS encryption with automatic key rotation
Point-in-time recovery enabled
Deletion protection enabled, plus a prevent_destroy lifecycle guard
Table name registered in Runtime Config under the dynamodb namespace in AWS AppConfig

The core/runtime-config/appconfig module exposes the dynamodb namespace by default, so the table name is deployed without further configuration. If you pass namespaces to that module explicitly, keep dynamodb in the list — otherwise no configuration profile is created for it and the generated table client cannot resolve the table name.

Deletion Protection

The table is protected by two independent guards, so that turning off either one alone cannot delete your data:

CDK
Terraform

deletionProtection, enforced by DynamoDB.
RemovalPolicy.RETAIN, enforced by CloudFormation, which leaves the table in place when it is removed from the stack.

deletion_protection_enabled, enforced by DynamoDB.
lifecycle { prevent_destroy = true } on the table in common/terraform/src/core/dynamodb/dynamodb.tf, enforced by Terraform, which fails any plan that would destroy the table.

Deleting the Table

Disable protection for environments where table deletion is expected, such as short-lived development or preview stacks.

CDK
Terraform

import { RemovalPolicy } from 'aws-cdk-lib';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  deletionProtection: false,
  removalPolicy: RemovalPolicy.DESTROY,
});

module "my_table" {
  source                      = "../../common/terraform/src/app/dynamodb/my-table"
  deletion_protection_enabled = false
}

prevent_destroy must be a literal — Terraform does not allow it to reference a variable — so it cannot be turned off from main.tf. Also remove the lifecycle block from the table in common/terraform/src/core/dynamodb/dynamodb.tf:

resource "aws_dynamodb_table" "table" {
  # ...

  lifecycle {
    prevent_destroy = true
  }
}

Billing Mode

The table defaults to on-demand (PAY_PER_REQUEST) billing. Switch to provisioned capacity for predictable, high-throughput workloads.

CDK
Terraform

import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  billingMode: BillingMode.PROVISIONED,
  readCapacity: 5,
  writeCapacity: 5,
});

module "my_table" {
  source       = "../../common/terraform/src/app/dynamodb/my-table"
  billing_mode = "PROVISIONED"
}

Point-in-time Recovery

Point-in-time recovery is enabled by default, allowing you to restore the table to any point in the last 35 days.

import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
});

module "my_table" {
  source                         = "../../common/terraform/src/app/dynamodb/my-table"
  point_in_time_recovery_enabled = false
}

Encryption

The table is encrypted with a customer-managed KMS key by default, created automatically for you. Switch to an AWS managed key, the AWS owned key, or bring your own KMS key, if you manage encryption differently.

Use an AWS Managed Key

Uses the shared aws/dynamodb KMS key that AWS manages on your behalf. It’s visible in your account’s KMS console and billed per request, but there’s no key for you to create, rotate or delete.

CDK
Terraform

import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  encryption: TableEncryption.AWS_MANAGED,
});

Choosing AWS_MANAGED means the table is no longer encrypted with a customer-managed key, which fails Checkov’s CKV_AWS_119. Suppress it on the table:

import { suppressRules } from '@my-scope/common-constructs';

suppressRules(table.table, ['CKV_AWS_119'], 'Using an AWS managed key rather than a customer-managed CMK');

module "my_table" {
  source     = "../../common/terraform/src/app/dynamodb/my-table"
  encryption = "AWS_MANAGED"
}

Use the AWS Owned Key

Uses a key fully owned and managed by AWS — free, with no key visible in your account at all. The simplest option when you don’t need a customer- or account-visible key for compliance reasons.

CDK
Terraform

import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  encryption: TableEncryption.DEFAULT,
});

Choosing DEFAULT means the table is no longer encrypted with a customer-managed key, which fails Checkov’s CKV_AWS_119. Suppress it on the table:

import { suppressRules } from '@my-scope/common-constructs';

suppressRules(table.table, ['CKV_AWS_119'], 'Using the AWS owned key rather than a customer-managed CMK');

module "my_table" {
  source     = "../../common/terraform/src/app/dynamodb/my-table"
  encryption = "DEFAULT"
}

Switching away from CUSTOMER_MANAGED

On an already-deployed table, changing encryption away from CUSTOMER_MANAGED (to either AWS_MANAGED or DEFAULT) in a single terraform apply fails: Terraform destroys the customer-managed key before updating the table, and DynamoDB then rejects the update because the key is already pending deletion.

Work around it by updating the table’s encryption directly via the AWS CLI first, then letting Terraform catch up and clean up the orphaned key:

# For AWS_MANAGED:
aws dynamodb update-table --table-name <table-name> \
  --sse-specification Enabled=true,SSEType=KMS,KMSMasterKeyId=alias/aws/dynamodb

# For DEFAULT:
aws dynamodb update-table --table-name <table-name> --sse-specification Enabled=false

# Then wait for this to report ENABLED (or for SSEDescription to disappear, for DEFAULT):
aws dynamodb describe-table --table-name <table-name> --query Table.SSEDescription.Status

Then update encryption in your Terraform config and run terraform apply as normal — Terraform now only needs to destroy the already-unused key, with nothing left depending on it.

Use Your Own KMS Key

Provide an existing customer-managed key instead of having one created for you. The key must already grant the DynamoDB service the permissions it needs in its own key policy.

CDK
Terraform

import { Key } from 'aws-cdk-lib/aws-kms';
import { MyTable } from '@my-scope/common-constructs';

const key = Key.fromKeyArn(this, 'Key', 'arn:aws:kms:us-east-1:111111111111:key/my-key-id');

const table = new MyTable(this, 'Table', {
  encryptionKey: key,
});

module "my_table" {
  source      = "../../common/terraform/src/app/dynamodb/my-table"
  kms_key_arn = "arn:aws:kms:us-east-1:111111111111:key/my-key-id"
}

Encryption Key Rotation

When the table creates its own customer-managed KMS key (the default, and only when you haven’t provided your own key), that key has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.

Disable Encryption Key Rotation

CDK
Terraform

import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  enableKeyRotation: false,
});

Disabling key rotation, or bringing your own key that doesn’t rotate, fails Checkov’s CKV_AWS_7. Suppress it on the key:

import { suppressRules } from '@my-scope/common-constructs';

suppressRules(table.table.encryptionKey!, ['CKV_AWS_7'], 'Key rotation is managed externally');

module "my_table" {
  source              = "../../common/terraform/src/app/dynamodb/my-table"
  enable_key_rotation = false
}

Connections

Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

FastAPI to Python DynamoDBConnect a FastAPI to a DynamoDB table

Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table

Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table