TypeScript DynamoDB

このジェネレーターは、Amazon DynamoDB をバックエンドとする新しい TypeScript DynamoDB プロジェクトを作成します。型安全なエンティティモデリングには ElectroDB を使用します。AWS CDK または Terraform を使用して DynamoDB テーブルをプロビジョニングおよび管理するために必要なアプリケーションコードとインフラストラクチャを生成し、シングルテーブル設計のサポートと DynamoDB Local によるローカル開発機能を備えています。

使用方法

TypeScript DynamoDB プロジェクトを生成する

CLI
VSCode

pnpm nx g @aws/nx-plugin:ts#dynamodb

yarn nx g @aws/nx-plugin:ts#dynamodb

npx nx g @aws/nx-plugin:ts#dynamodb

bunx nx g @aws/nx-plugin:ts#dynamodb

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:ts#dynamodb --dry-run

yarn nx g @aws/nx-plugin:ts#dynamodb --dry-run

npx nx g @aws/nx-plugin:ts#dynamodb --dry-run

bunx nx g @aws/nx-plugin:ts#dynamodb --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - ts#dynamodb
必須パラメータを入力
クリック Generate

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	生成するDynamoDBプロジェクトの名前
directory	string	packages	プロジェクトを保存するディレクトリ
subDirectory	string	-	プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
framework	electrodb	electrodb	DynamoDB エンティティに使用するフレームワーク。
tableName	string	-	DynamoDB テーブル名。指定しない場合は自動生成されます。
infra	dynamodb \| none	dynamodb	DynamoDBテーブルのためにプロビジョニングするインフラストラクチャ。
iac	inherit \| cdk \| terraform	inherit	優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合は false に設定します（後続のジェネレーターが Nx プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは <directory>/<name> ディレクトリに以下のプロジェクト構造を作成します：

Directorysrc
- index.ts Project entry point and exports
- client.ts DynamoDB client singleton and table name resolution
- Directoryentities
  - example.ts Example ElectroDB entity definition
  - index.ts Entity exports
config.json Table configuration including GSI definitions and local development settings
package.json Project manifest defining the project’s package name and dependencies
project.json Project configuration and build targets

ローカル開発スクリプトは、すべての DynamoDB プロジェクト（TypeScript と Python の両方）で共有され、以下に一度生成されます：

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

インフラストラクチャ

このジェネレーターは、選択した iac に基づいてインフラストラクチャをコードとして提供するため、関連する CDK コンストラクトまたは Terraform モジュールを含む packages/common にプロジェクトを作成します。

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用のコンストラクト
    …
  - Directorycore/ app 内のコンストラクトによって再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用の Terraform モジュール
    …
  - Directorycore/ app 内のモジュールによって再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directorydynamodb
    <name>.ts テーブル固有のインフラストラクチャ
- Directorycore
  - dynamodb.ts 汎用 DynamoDB テーブルコンストラクト

ローカル開発

ローカル DynamoDB の起動

ジェネレーターは、DynamoDB Local インスタンスを起動してテーブルを作成する dev ターゲットを設定します。プロジェクトの dev ターゲットを使用してください：

pnpm nx dev <project-name>

yarn nx dev <project-name>

npx nx dev <project-name>

bunx nx dev <project-name>

これにより自動的に以下が実行されます：

DynamoDB Local イメージをプル（pull-image ターゲット）
コンテナを起動
config.json で定義されたインデックスを持つローカルテーブルを作成

データモデリング

生成されたプロジェクトは、単一の DynamoDB テーブル上で型安全なエンティティモデリングを行うために ElectroDB を使用し、DynamoDB のシングルテーブル設計に従います。生成されたサンプルエンティティを出発点として、src/entities/ 配下にエンティティファイルを追加または更新してください。

エンティティ定義の例：

import { Entity } from 'electrodb';
import { getDynamoDBClient, resolveTableName } from '../client.js';

export const createExampleEntity = async () =>
  new Entity(
    {
      model: {
        entity: 'example',
        version: '1',
        service: 'MyTable',
      },
      attributes: {
        id: {
          type: 'string',
          required: true,
        },
        createdAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          readOnly: true,
        },
        updatedAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          watch: '*',
          set: () => new Date().toISOString(),
        },
      },
      indexes: {
        primary: {
          pk: {
            field: 'pk',
            composite: ['id'],
          },
          sk: {
            field: 'sk',
            composite: [],
          },
        },
      },
    },
    { client: getDynamoDBClient(), table: await resolveTableName() },
  );

詳細については、ElectroDB エンティティドキュメントを参照してください。

DynamoDB クライアントの使用

生成された src/client.ts は、2つの主要なユーティリティをエクスポートします：

getDynamoDBClient() — キャッシュされたシングルトンの DynamoDBClient を返します。LOCAL_DEV=true の場合、ローカルの DynamoDB Local インスタンスに接続します。それ以外の場合は、デフォルトの認証情報チェーンを使用して AWS クライアントを作成します。
resolveTableName() — DynamoDB テーブル名を返します。LOCAL_DEV=true の場合、ローカルテーブル名定数を返します。それ以外の場合は、RUNTIME_CONFIG_APP_ID 環境変数を使用して AWS AppConfig から名前を取得し、後続の呼び出しのためにキャッシュします。

ローカル DynamoDB の停止

dev を停止する（例：Ctrl+C で）と、DynamoDB Local コンテナは自動的に削除されますが、名前付きボリュームは保持されるため、データは再起動後も保持されます。

Windows でのシグナル処理の制限により、dev を停止してもコンテナは自動的に削除されません。手動で削除する必要があります：

<engine> rm -f <scope>-dynamodb

<engine> をコンテナエンジン（docker または finch）に、<scope> を Nx ワークスペースのスコープ（例：proj）に置き換えてください。

グローバルセカンダリインデックスの追加/削除

GSI は、プロジェクトルートの config.json の tableConfig.globalSecondaryIndexes キーで定義されます。GSI キーのシングルテーブル設計命名規則に従って、各 GSI のエントリを追加してください：

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

sortKeyフィールドは、ハッシュキーのみのGSIの場合はオプションです。

この設定ファイルは、すべての利用者が読み取る唯一の信頼できる情報源です：

ローカル開発 — devはconfig.jsonを読み取り、GSIリストに一致するようにローカルテーブルを作成または更新します
CDK — コンストラクトは合成時にconfig.jsonを読み取るため、GSIの変更は次回のcdk deployに反映されます
Terraform — モジュールはplan/apply時にconfig.jsonを読み取ります

デプロイごとに1つのGSI

テーブルへの接続

任意の TypeScript プロジェクトで、DynamoDB パッケージからエンティティファクトリをインポートして直接使用します：

import { createExampleEntity } from '@my-scope/my-table';

const entity = await createExampleEntity();
const result = await entity.query.primary({ id: '123' }).go();

内部的には、createExampleEntity() は resolveTableName() を呼び出して、実行時に AWS AppConfig からテーブル名を取得します。

テーブルのデプロイ

DynamoDBジェネレーターは、選択したiacに基づいてCDKまたはTerraformインフラストラクチャを作成します。

CDK
Terraform

CDKコンストラクトはcommon/constructsに作成されます。使用例：

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');
  }
}

これにより、以下の設定でDynamoDBテーブルがプロビジョニングされます：

pk（パーティションキー）とsk（ソートキー）、両方ともString型
config.jsonで定義されたグローバルセカンダリインデックス
オンデマンド（PAY_PER_REQUEST）課金
自動キーローテーション付きのカスタマー管理KMS暗号化
ポイントインタイムリカバリが有効
削除保護が有効
AWS AppConfigのdynamodb名前空間下のランタイム設定にテーブル名が登録される

Terraformモジュールはcommon/terraformに作成されます。使用例：

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

これにより、以下の設定でDynamoDBテーブルがプロビジョニングされます：

pk（パーティションキー）とsk（ソートキー）、両方ともString型
config.jsonで定義されたグローバルセカンダリインデックス
オンデマンド（PAY_PER_REQUEST）課金
自動キーローテーション付きのカスタマー管理KMS暗号化
ポイントインタイムリカバリが有効
削除保護が有効
ランタイム設定にテーブル名が登録される

削除保護

削除保護はデフォルトで有効になっており、誤ってテーブルを削除することを防ぎます。

削除保護の無効化

短期間の開発環境やプレビュースタックなど、テーブルの削除が想定される環境では無効にします。

CDK
Terraform

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

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

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

課金モード

テーブルはデフォルトでオンデマンド（PAY_PER_REQUEST）課金になります。予測可能で高スループットのワークロードには、プロビジョニングされたキャパシティに切り替えます。

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"
}

ポイントインタイムリカバリ

ポイントインタイムリカバリはデフォルトで有効になっており、過去35日間の任意の時点にテーブルを復元できます。

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
}

暗号化キーのローテーション

テーブルの暗号化に使用されるKMSキーは、デフォルトで自動キーローテーションが有効になっています。セキュリティポリシーで外部的にローテーションを管理している場合は無効にします。

暗号化キーのローテーションの無効化

CDK
Terraform

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

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

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

接続

connection ジェネレーターを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合します。このプロジェクトに関連する接続は以下の通りです：

tRPC API to TypeScript DynamoDBtRPC API を DynamoDB テーブルに接続する

Smithy API to TypeScript DynamoDBSmithy API を DynamoDB テーブルに接続する

TypeScript Agent to TypeScript DynamoDBTypeScript Agent を DynamoDB テーブルに接続する

MCP Server to TypeScript DynamoDBTypeScript MCP Server を DynamoDB テーブルに接続する