TypeScript DynamoDB

Questo generatore crea un nuovo progetto TypeScript DynamoDB basato su Amazon DynamoDB, utilizzando ElectroDB per la modellazione di entità type-safe. Genera il codice dell’applicazione e l’infrastruttura necessaria per il provisioning e la gestione di una tabella DynamoDB utilizzando AWS CDK o Terraform, con supporto per il design single-table e sviluppo locale integrato tramite DynamoDB Local.

Utilizzo

Genera un Progetto TypeScript DynamoDB

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#dynamodb
5. Compila i parametri richiesti
6. Clicca su Generate

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto DynamoDB da generare
directory	string	packages	La directory in cui memorizzare il progetto.
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
framework	electrodb	electrodb	Il framework da utilizzare per le entità DynamoDB.
tableName	string	-	Il nome della tabella DynamoDB. Generato automaticamente se non specificato.
infra	dynamodb | none	dynamodb	Infrastruttura da fornire per la tabella DynamoDB.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore crea la seguente struttura di progetto nella directory <directory>/<name>:

• Directorysrc

  • index.ts Punto di ingresso del progetto ed esportazioni
  • client.ts Singleton del client DynamoDB e risoluzione del nome della tabella
  • Directoryentities

    • example.ts Esempio di definizione di entità ElectroDB
    • index.ts Esportazioni delle entità
• config.json Configurazione della tabella incluse le definizioni GSI e le impostazioni di sviluppo locale
• project.json Configurazione del progetto e target di build

Gli script di sviluppo locale sono condivisi tra tutti i progetti DynamoDB (sia TypeScript che Python) e generati una volta in:

• Directorypackages/common/scripts/src/dynamodb

  • create-local-table.ts Crea la tabella DynamoDB nell’istanza locale di DynamoDB Local
  • pull-image.ts Scarica l’immagine di DynamoDB Local
  • start-container.ts Avvia il container di DynamoDB Local

Infrastruttura

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorydynamodb

      • <name>.ts Infrastruttura specifica per la tua tabella
  • Directorycore

    • dynamodb.ts Costrutto generico per tabelle DynamoDB

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorydynamodb

      • Directory<name>

        • <name>.tf Modulo specifico per la tua tabella
  • Directorycore

    • Directorydynamodb

      • dynamodb.tf Modulo generico DynamoDB

Sviluppo Locale

Avvio di DynamoDB Locale

Il generatore configura un target dev che avvia un’istanza di DynamoDB Local e crea la tabella. Usa il target dev del progetto:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Questo automaticamente:

1. Scarica l’immagine DynamoDB Local (target pull-image)
2. Avvia un container
3. Crea una tabella locale con gli indici definiti in config.json

Modellazione dei Dati

Il progetto generato utilizza ElectroDB per la modellazione di entità type-safe su una singola tabella DynamoDB, seguendo il design single-table di DynamoDB. Aggiungi o aggiorna i file delle entità in src/entities/, utilizzando l’entità di esempio generata come punto di partenza.

Esempio di definizione di entità:

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

Per maggiori dettagli, consulta la documentazione delle entità ElectroDB.

Utilizzo del Client DynamoDB

Il file generato src/client.ts esporta due utility chiave:

• getDynamoDBClient() — restituisce un singleton DynamoDBClient in cache. Quando LOCAL_DEV=true, si connette all’istanza locale di DynamoDB Local; altrimenti crea un client AWS utilizzando la catena di credenziali predefinita.
• resolveTableName() — restituisce il nome della tabella DynamoDB. Quando LOCAL_DEV=true, restituisce la costante del nome della tabella locale; altrimenti recupera il nome da AWS AppConfig utilizzando la variabile d’ambiente RUNTIME_CONFIG_APP_ID e lo memorizza in cache per le chiamate successive.

Arresto di DynamoDB Locale

L’arresto di dev (ad es. con Ctrl+C) rimuove automaticamente il container DynamoDB Local, ma preserva il volume nominato in modo che i tuoi dati persistano tra i riavvii.

Windows

A causa di limitazioni nella gestione dei segnali su Windows, il container non viene rimosso automaticamente quando dev viene arrestato. Sarà necessario rimuoverlo manualmente:

<engine> rm -f <scope>-dynamodb

Sostituisci <engine> con il tuo motore di container (docker o finch) e <scope> con lo scope del tuo workspace Nx (ad es. proj).

Aggiunta/Rimozione di Global Secondary Index

I GSI sono definiti in config.json nella radice del progetto sotto la chiave tableConfig.globalSecondaryIndexes. Aggiungi una voce per ogni GSI, seguendo la convenzione di denominazione del design single-table per le chiavi GSI:

config.json

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

Il campo sortKey è opzionale per i GSI con solo hash-key.

Questo file di configurazione è l’unica fonte di verità letta da tutti i consumatori:

• Sviluppo locale — dev legge config.json e crea o aggiorna la tabella locale per corrispondere all’elenco dei GSI
• CDK — il costrutto legge config.json al momento della sintesi, quindi le modifiche ai GSI si riflettono al prossimo cdk deploy
• Terraform — il modulo legge config.json al momento del plan/apply

Un GSI per Deployment

Attenzione

DynamoDB non consente la creazione o l’eliminazione di più di un GSI in un singolo aggiornamento della tabella.

Ogni deployment può aggiungere o rimuovere al massimo un GSI. Se è necessario aggiungere o rimuovere più GSI, farlo uno alla volta — aggiornare config.json e le classi di entità rilevanti, distribuire lo stack, quindi ripetere per la modifica successiva.

Connessione alla Tabella

In qualsiasi progetto TypeScript, importa le factory delle entità dal tuo package DynamoDB e utilizzale direttamente:

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

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

Configurazione runtime

Quando viene eseguito in AWS, resolveTableName() recupera il nome della tabella da AWS AppConfig utilizzando la variabile d’ambiente RUNTIME_CONFIG_APP_ID. I progetti costruiti con questo plugin (API tRPC, API Smithy, agenti, server MCP) hanno già questa variabile configurata automaticamente. Per altri progetti TypeScript, assicurati che RUNTIME_CONFIG_APP_ID sia impostata nell’ambiente di runtime con l’ID dell’applicazione AppConfig fornito dalla tua infrastruttura. Per maggiori informazioni, consulta la guida alla Configurazione Runtime.

Deployment della Tabella

Il generatore DynamoDB crea infrastruttura CDK o Terraform in base al tuo iac selezionato.

CDK

Il costrutto CDK viene creato in common/constructs. Esempio di utilizzo:

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

Questo esegue il provisioning di una tabella DynamoDB con:

• pk (partition key) e sk (sort key), entrambe di tipo String
• Global Secondary Indexes come definiti in config.json
• Fatturazione on-demand (PAY_PER_REQUEST)
• Crittografia KMS gestita dal cliente con rotazione automatica delle chiavi
• Point-in-time recovery abilitato
• Protezione dalla cancellazione abilitata
• Nome della tabella registrato in Runtime Config sotto il namespace dynamodb in AWS AppConfig

Terraform

Il modulo Terraform viene creato in common/terraform. Esempio di utilizzo:

packages/infra/src/main.tf

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

Questo esegue il provisioning di una tabella DynamoDB con:

• pk (partition key) e sk (sort key), entrambe di tipo String
• Global Secondary Indexes come definiti in config.json
• Fatturazione on-demand (PAY_PER_REQUEST)
• Crittografia KMS gestita dal cliente con rotazione automatica delle chiavi
• Point-in-time recovery abilitato
• Protezione dalla cancellazione abilitata
• Nome della tabella registrato in Runtime Config

Concessione dell’accesso

Per consentire alle funzioni Lambda di accedere alla tabella DynamoDB, concedi le autorizzazioni necessarie nella tua infrastruttura.

CDK

Chiama grantReadWriteData sul costrutto della tabella. Questo concede sia le autorizzazioni DynamoDB che KMS richieste dal ruolo di esecuzione Lambda:

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

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

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

const api = new Api(this, 'Api', {
  integrations: Api.defaultIntegrations(this).build(),
});

Object.entries(api.integrations).forEach(([, integration]) => {
  table.grantReadWriteData(integration.handler);
});

Nota

Questo esempio concede l’accesso a ogni handler nella tua API. Se solo alcuni handler necessitano di accesso, configurali individualmente.

Terraform

Concedi al ruolo di esecuzione Lambda l’autorizzazione per accedere alla tabella DynamoDB e alla sua chiave di crittografia KMS:

packages/infra/src/main.tf

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

resource "aws_iam_role_policy" "dynamodb_access" {
  role = module.my_api.lambda_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "dynamodb:GetItem",
          "dynamodb:PutItem",
          "dynamodb:UpdateItem",
          "dynamodb:DeleteItem",
          "dynamodb:Query",
          "dynamodb:Scan",
          "dynamodb:BatchGetItem",
          "dynamodb:BatchWriteItem",
        ]
        Resource = [
          module.my_table.table_arn,
          "${module.my_table.table_arn}/index/*",
        ]
      },
      {
        Effect = "Allow"
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = [module.my_table.kms_key_arn]
      },
    ]
  })
}

Protezione dalla cancellazione

La protezione dalla cancellazione è abilitata per impostazione predefinita per prevenire la cancellazione accidentale della tabella.

Disabilitare la protezione dalla cancellazione

Disabilitala per ambienti in cui è prevista la cancellazione della tabella, come stack di sviluppo o preview di breve durata.

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
}

Modalità di fatturazione

La tabella utilizza per impostazione predefinita la fatturazione on-demand (PAY_PER_REQUEST). Passa alla capacità con provisioning per carichi di lavoro prevedibili ad 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"
}

Point-in-time Recovery

Il Point-in-time recovery è abilitato per impostazione predefinita, consentendoti di ripristinare la tabella a qualsiasi punto negli ultimi 35 giorni.

Disabilitare il Point-in-time Recovery

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
}

Rotazione della chiave di crittografia

La chiave KMS utilizzata per crittografare la tabella ha la rotazione automatica delle chiavi abilitata per impostazione predefinita. Disabilitala se la tua policy di sicurezza gestisce la rotazione esternamente.

Disabilitare la rotazione della chiave di crittografia

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
}

Connessioni

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

tRPC API to TypeScript DynamoDB Collega un'API tRPC a una tabella DynamoDB

Smithy API to TypeScript DynamoDB Collega un'API Smithy a una tabella DynamoDB

TypeScript Agent to TypeScript DynamoDB Collega un TypeScript Agent a una tabella DynamoDB

MCP Server to TypeScript DynamoDB Collega un MCP Server TypeScript a una tabella DynamoDB