TypeScript DynamoDB

이 생성기는 Amazon DynamoDB를 기반으로 하는 새로운 TypeScript DynamoDB 프로젝트를 생성하며, 타입 안전 엔티티 모델링을 위해 ElectroDB를 사용합니다. AWS CDK 또는 Terraform을 사용하여 DynamoDB 테이블을 프로비저닝하고 관리하는 데 필요한 애플리케이션 코드와 인프라를 생성하며, 단일 테이블 설계 지원과 DynamoDB Local을 통한 로컬 개발 환경을 내장하고 있습니다.

사용법

TypeScript DynamoDB 프로젝트 생성하기

CLI

pnpm

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

yarn

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

npm

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

bun

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

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

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

yarn

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

npm

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

bun

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

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#dynamodb
5. 필수 매개변수 입력
6. 클릭 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> 디렉토리에 다음과 같은 프로젝트 구조를 생성합니다:

• 디렉터리src

  • index.ts Project entry point and exports
  • client.ts DynamoDB client singleton and table name resolution
  • 디렉터리entities

    • 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 모두)에서 공유되며 다음 위치에 한 번 생성됩니다:

• 디렉터리packages/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 constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs

      • …
    • 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs

      • …
    • index.ts app에서 constructs를 내보내는 진입점
  • project.json 프로젝트 빌드 타겟 및 구성

생성된 프로젝트

이 프로젝트는 ts#project 생성기를 사용하여 생성되므로 동일한 빌드 타겟을 구성합니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Terraform 모듈

      • …
    • 디렉터리core/ app의 모듈에서 재사용되는 일반 모듈

      • …
  • project.json 프로젝트 빌드 타겟 및 구성

생성된 프로젝트

이 프로젝트는 terraform#project 생성기를 사용하여 생성되므로 동일한 빌드 타겟을 구성합니다.

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리app

    • 디렉터리dynamodb

      • <name>.ts 테이블에 특정한 인프라
  • 디렉터리core

    • dynamodb.ts 범용 DynamoDB 테이블 구성

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리app

    • 디렉터리dynamodb

      • 디렉터리<name>

        • <name>.tf 테이블에 특정한 모듈
  • 디렉터리core

    • 디렉터리dynamodb

      • dynamodb.tf 범용 DynamoDB 모듈

로컬 개발

로컬 DynamoDB 시작하기

생성기는 DynamoDB Local 인스턴스를 시작하고 테이블을 생성하는 dev 타겟을 구성합니다. 프로젝트의 dev 타겟을 사용하세요:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

이것은 자동으로:

1. DynamoDB Local 이미지를 가져옵니다 (pull-image 타겟)
2. 컨테이너를 시작합니다
3. config.json에 정의된 인덱스로 로컬 테이블을 생성합니다

데이터 모델링

생성된 프로젝트는 단일 DynamoDB 테이블에서 타입 안전 엔티티 모델링을 위해 ElectroDB를 사용하며, DynamoDB의 단일 테이블 설계를 따릅니다. 생성된 예제 엔티티를 시작점으로 사용하여 src/entities/ 아래에 엔티티 파일을 추가하거나 업데이트하세요.

엔티티 정의 예제:

packages/my-table/src/entities/example.ts

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는 두 가지 주요 유틸리티를 내보냅니다:

• 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

Windows의 신호 처리 제한으로 인해 dev가 중지될 때 컨테이너가 자동으로 제거되지 않습니다. 수동으로 제거해야 합니다:

<engine> rm -f <scope>-dynamodb

<engine>을 컨테이너 엔진(docker 또는 finch)으로, <scope>를 Nx 워크스페이스 스코프(예: proj)로 바꾸세요.

글로벌 보조 인덱스 추가/제거

GSI는 프로젝트 루트의 config.json에서 tableConfig.globalSecondaryIndexes 키 아래에 정의됩니다. GSI 키에 대한 단일 테이블 설계 명명 규칙을 따라 각 GSI에 대한 항목을 추가하세요:

config.json

{
  ...
  "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을 읽습니다

배포당 하나의 GSI

주의

DynamoDB는 단일 테이블 업데이트에서 둘 이상의 GSI를 생성하거나 삭제하는 것을 허용하지 않습니다.

각 배포는 최대 하나의 GSI를 추가하거나 제거할 수 있습니다. 여러 GSI를 추가하거나 제거해야 하는 경우 한 번에 하나씩 수행하세요 — config.json과 관련 엔티티 클래스를 업데이트하고 스택을 배포한 다음 다음 변경 사항에 대해 반복합니다.

테이블에 연결하기

모든 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에서 테이블 이름을 가져옵니다.

Runtime config

이는 런타임에 AWS AppConfig에서 구성을 가져오기 위해 RUNTIME_CONFIG_APP_ID 환경 변수에 의존합니다. 이 플러그인으로 빌드된 프로젝트(API, Agent, MCP 서버)는 이미 이 변수가 자동으로 구성되어 있습니다. 다른 프로젝트의 경우, 인프라에서 프로비저닝한 AppConfig 애플리케이션 ID로 런타임 환경에 RUNTIME_CONFIG_APP_ID가 설정되어 있는지 확인하세요. 자세한 내용은 런타임 구성 가이드를 참조하세요.

테이블 배포하기

DynamoDB 생성기는 선택한 iac에 따라 CDK 또는 Terraform 인프라를 생성합니다.

CDK

CDK 구성은 common/constructs에 생성됩니다. 사용 예시:

packages/infra/src/stacks/application-stack.ts

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 네임스페이스 아래 Runtime Config에 등록된 테이블 이름

Terraform

Terraform 모듈은 common/terraform에 생성됩니다. 사용 예시:

packages/infra/src/main.tf

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

다음과 같은 DynamoDB 테이블을 프로비저닝합니다:

• pk (파티션 키)와 sk (정렬 키), 둘 다 String 타입
• config.json에 정의된 글로벌 보조 인덱스
• 온디맨드 (PAY_PER_REQUEST) 요금제
• 자동 키 로테이션이 활성화된 고객 관리형 KMS 암호화
• 특정 시점 복구 활성화
• 삭제 방지 활성화
• Runtime Config에 등록된 테이블 이름

삭제 방지

실수로 테이블이 삭제되는 것을 방지하기 위해 삭제 방지가 기본적으로 활성화되어 있습니다.

삭제 방지 비활성화

단기 개발 또는 프리뷰 스택과 같이 테이블 삭제가 예상되는 환경에서는 비활성화하세요.

CDK

packages/infra/src/stacks/application-stack.ts

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

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

Terraform

packages/infra/src/main.tf

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

요금제 모드

테이블은 기본적으로 온디맨드 (PAY_PER_REQUEST) 요금제를 사용합니다. 예측 가능한 고처리량 워크로드의 경우 프로비저닝된 용량으로 전환하세요.

CDK

packages/infra/src/stacks/application-stack.ts

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

Terraform

packages/infra/src/main.tf

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

특정 시점 복구

특정 시점 복구는 기본적으로 활성화되어 있으며, 지난 35일 동안의 임의 시점으로 테이블을 복원할 수 있습니다.

특정 시점 복구 비활성화

CDK

packages/infra/src/stacks/application-stack.ts

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

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

Terraform

packages/infra/src/main.tf

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

암호화 키 로테이션

테이블을 암호화하는 데 사용되는 KMS 키는 기본적으로 자동 키 로테이션이 활성화되어 있습니다. 보안 정책에서 로테이션을 외부적으로 관리하는 경우 비활성화하세요.

암호화 키 로테이션 비활성화

CDK

packages/infra/src/stacks/application-stack.ts

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

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

Terraform

packages/infra/src/main.tf

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 테이블에 연결하기