TypeScript DynamoDB

Questo generatore crea un nuovo progetto TypeScript DynamoDB supportato da 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

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

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

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

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

Infrastruttura

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

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

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

Progetto Generato

Questo progetto è generato utilizzando il generatore ts#project e quindi configura gli stessi target di 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

Progetto Generato

Questo progetto è generato utilizzando il generatore terraform#project 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 di 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 esempio 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. Dovrai 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 esempio 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 delle chiavi GSI del design single-table:

config.json

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

Il campo sortKey è facoltativo 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à pertinenti, distribuire lo stack, quindi ripetere per la modifica successiva.

Connessione alla tabella

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

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

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

Dietro le quinte, createExampleEntity() chiama resolveTableName() per recuperare il nome della tabella da AWS AppConfig a runtime.

Configurazione runtime

Questo si basa sulla variabile d’ambiente RUNTIME_CONFIG_APP_ID per recuperare la configurazione da AWS AppConfig durante l’esecuzione. I progetti costruiti con questo plugin (API, Agents, server MCP) hanno già questa variabile configurata automaticamente. Per altri progetti, assicurati che RUNTIME_CONFIG_APP_ID sia impostata nell’ambiente di esecuzione con l’ID dell’applicazione AppConfig fornito dalla tua infrastruttura. Per maggiori informazioni, consulta la guida alla Configurazione Runtime.

Distribuzione 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

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 momento 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 delle chiavi 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 delle chiavi 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

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

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