TypeScript DynamoDB

Este gerador cria um novo projeto TypeScript DynamoDB apoiado pelo Amazon DynamoDB, usando ElectroDB para modelagem de entidades com segurança de tipo. Ele gera o código da aplicação e a infraestrutura necessária para provisionar e gerenciar uma tabela DynamoDB usando AWS CDK ou Terraform, com suporte para design de tabela única e desenvolvimento local integrado via DynamoDB Local.

Uso

Gerar um Projeto 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#dynamodb
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	Nome do projeto DynamoDB a ser gerado
directory	string	packages	O diretório onde armazenar o projeto.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
framework	electrodb	electrodb	O framework a ser usado para entidades DynamoDB.
tableName	string	-	O nome da tabela DynamoDB. Gerado automaticamente se não especificado.
infra	dynamodb | none	dynamodb	Infraestrutura a provisionar para a tabela DynamoDB.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador cria a seguinte estrutura de projeto no diretório <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

Os scripts de desenvolvimento local são compartilhados entre todos os projetos DynamoDB (tanto TypeScript quanto Python) e gerados uma vez em:

• 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

Infraestrutura

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

CDK

• 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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

Terraform

• 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

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorydynamodb

      • <name>.ts Infraestrutura específica para sua tabela
  • Directorycore

    • dynamodb.ts Construto genérico de tabela DynamoDB

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorydynamodb

      • Directory<name>

        • <name>.tf Módulo específico para sua tabela
  • Directorycore

    • Directorydynamodb

      • dynamodb.tf Módulo genérico DynamoDB

Desenvolvimento Local

Iniciando o DynamoDB Local

O gerador configura um target dev que inicia uma instância do DynamoDB Local e cria a tabela. Use o target dev do projeto:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Isso automaticamente:

1. Baixa a imagem do DynamoDB Local (target pull-image)
2. Inicia um container
3. Cria uma tabela local com os índices definidos em config.json

Modelagem de Dados

O projeto gerado usa ElectroDB para modelagem de entidades com segurança de tipo em uma única tabela DynamoDB, seguindo o design de tabela única do DynamoDB. Adicione ou atualize arquivos de entidade em src/entities/, usando a entidade de exemplo gerada como ponto de partida.

Exemplo de definição de entidade:

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

Para mais detalhes, consulte a documentação de entidades do ElectroDB.

Usando o Cliente DynamoDB

O src/client.ts gerado exporta dois utilitários principais:

• getDynamoDBClient() — retorna um singleton DynamoDBClient em cache. Quando LOCAL_DEV=true, conecta-se à instância local do DynamoDB Local; caso contrário, cria um cliente AWS usando a cadeia de credenciais padrão.
• resolveTableName() — retorna o nome da tabela DynamoDB. Quando LOCAL_DEV=true, retorna a constante do nome da tabela local; caso contrário, busca o nome do AWS AppConfig usando a variável de ambiente RUNTIME_CONFIG_APP_ID e o armazena em cache para chamadas subsequentes.

Parando o DynamoDB Local

Parar o dev (por exemplo, com Ctrl+C) remove automaticamente o contêiner DynamoDB Local, mas preserva o volume nomeado para que seus dados persistam entre reinicializações.

Windows

Devido a limitações no tratamento de sinais no Windows, o contêiner não é removido automaticamente quando o dev é interrompido. Você precisará removê-lo manualmente:

<engine> rm -f <scope>-dynamodb

Substitua <engine> pelo seu motor de contêiner (docker ou finch) e <scope> pelo escopo do seu workspace Nx (por exemplo, proj).

Adicionando/Removendo Índices Secundários Globais

Os GSIs são definidos em config.json na raiz do projeto sob a chave tableConfig.globalSecondaryIndexes. Adicione uma entrada para cada GSI, seguindo a convenção de nomenclatura de chaves GSI do design de tabela única:

config.json

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

O campo sortKey é opcional para GSIs somente com chave de hash.

Este arquivo de configuração é a única fonte de verdade lida por todos os consumidores:

• Desenvolvimento local — dev lê config.json e cria ou atualiza a tabela local para corresponder à lista de GSI
• CDK — o construct lê config.json no momento da síntese, então as mudanças de GSI são refletidas no próximo cdk deploy
• Terraform — o módulo lê config.json no momento do plan/apply

Um GSI por Implantação

Cuidado

O DynamoDB não permite que mais de um GSI seja criado ou excluído em uma única atualização de tabela.

Cada implantação pode adicionar ou remover no máximo um GSI. Se você precisar adicionar ou remover múltiplos GSIs, faça isso um de cada vez — atualize config.json e as classes de entidade relevantes, implante a stack, e então repita para a próxima mudança.

Conectando-se à Tabela

Em qualquer projeto TypeScript, importe as fábricas de entidade do seu pacote DynamoDB e use-as diretamente:

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

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

Nos bastidores, createExampleEntity() chama resolveTableName() para buscar o nome da tabela do AWS AppConfig em tempo de execução.

Configuração em tempo de execução

Isso depende da variável de ambiente RUNTIME_CONFIG_APP_ID para buscar a configuração do AWS AppConfig em tempo de execução. Projetos construídos com este plugin (APIs, Agents, servidores MCP) já têm essa variável configurada automaticamente. Para outros projetos, certifique-se de que RUNTIME_CONFIG_APP_ID esteja definida no ambiente de execução com o ID do aplicativo AppConfig provisionado pela sua infraestrutura. Para mais informações, consulte o guia de Configuração em Tempo de Execução.

Implantando sua Tabela

O gerador DynamoDB cria infraestrutura CDK ou Terraform com base no seu iac selecionado.

CDK

O construtor CDK é criado em common/constructs. Exemplo de uso:

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

Isso provisiona uma tabela DynamoDB com:

• pk (chave de partição) e sk (chave de ordenação), ambas do tipo String
• Índices Secundários Globais conforme definido em config.json
• Cobrança sob demanda (PAY_PER_REQUEST)
• Criptografia KMS gerenciada pelo cliente com rotação automática de chaves
• Recuperação point-in-time habilitada
• Proteção contra exclusão habilitada
• Nome da tabela registrado no Runtime Config sob o namespace dynamodb no AWS AppConfig

Terraform

O módulo Terraform é criado em common/terraform. Exemplo de uso:

packages/infra/src/main.tf

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

Isso provisiona uma tabela DynamoDB com:

• pk (chave de partição) e sk (chave de ordenação), ambas do tipo String
• Índices Secundários Globais conforme definido em config.json
• Cobrança sob demanda (PAY_PER_REQUEST)
• Criptografia KMS gerenciada pelo cliente com rotação automática de chaves
• Recuperação point-in-time habilitada
• Proteção contra exclusão habilitada
• Nome da tabela registrado no Runtime Config

Proteção contra Exclusão

A proteção contra exclusão está habilitada por padrão para prevenir a exclusão acidental da tabela.

Desabilitar Proteção contra Exclusão

Desabilite-a para ambientes onde a exclusão da tabela é esperada, como stacks de desenvolvimento ou preview de curta duração.

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
}

Modo de Cobrança

A tabela usa por padrão cobrança sob demanda (PAY_PER_REQUEST). Mude para capacidade provisionada para cargas de trabalho previsíveis e de alto throughput.

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

Recuperação Point-in-time

Recuperação point-in-time está habilitada por padrão, permitindo que você restaure a tabela para qualquer ponto nos últimos 35 dias.

Desabilitar Recuperação Point-in-time

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
}

Rotação de Chave de Criptografia

A chave KMS usada para criptografar a tabela tem rotação automática de chaves habilitada por padrão. Desabilite-a se sua política de segurança gerencia a rotação externamente.

Desabilitar Rotação de Chave de Criptografia

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
}

Conexões

Use o gerador connection para integrar este projeto com outros no seu workspace. As seguintes conexões envolvem este projeto:

tRPC API to TypeScript DynamoDBConnect a tRPC API to a DynamoDB table

Smithy API to TypeScript DynamoDBConnect a Smithy API to a DynamoDB table

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table