TypeScript DynamoDB

Ce générateur crée un nouveau projet TypeScript DynamoDB soutenu par Amazon DynamoDB, utilisant ElectroDB pour la modélisation d’entités type-safe. Il génère le code d’application et l’infrastructure nécessaires pour provisionner et gérer une table DynamoDB en utilisant AWS CDK ou Terraform, avec prise en charge de la conception à table unique et développement local intégré via DynamoDB Local.

Utilisation

Générer un projet TypeScript DynamoDB

Exécuter ce générateur@aws/nx-plugin:ts#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

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - ts#dynamodb
Remplissez les paramètres requis
Cliquez sur Generate

Composez votre commande8

nameRequis

Options

Options du générateur8 options

nameRequisstring: Nom du projet DynamoDB à générer
directorystringPar défaut: packages: Le répertoire dans lequel stocker le projet.
frameworkenumPar défaut: electrodb: Le framework à utiliser pour les entités DynamoDB.
electrodb
infraenumPar défaut: dynamodb: Infrastructure à provisionner pour la table DynamoDB.
dynamodbnone
iacenumPar défaut: inherit: Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.
inheritcdkterraform
subDirectorystring: Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
tableNamestring: Le nom de la table DynamoDB. Généré automatiquement si non spécifié.
preferInstallDependenciesbooleanPar défaut: true: Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur crée la structure de projet suivante dans le répertoire <directory>/<name> :

Répertoiresrc
- index.ts Point d’entrée du projet et exports
- client.ts Singleton du client DynamoDB et résolution du nom de table
- Répertoireentities
  - example.ts Exemple de définition d’entité ElectroDB
  - index.ts Exports des entités
config.json Configuration de la table incluant les définitions GSI et les paramètres de développement local
package.json Manifeste du projet définissant le nom du package et les dépendances
project.json Configuration du projet et cibles de build

Les scripts de développement local sont partagés entre tous les projets DynamoDB (TypeScript et Python) et générés une fois dans :

Répertoirepackages/common/scripts/src/dynamodb
- create-local-table.ts Crée la table DynamoDB dans l’instance DynamoDB Local locale
- pull-image.ts Récupère l’image DynamoDB Local
- start-container.ts Démarre le conteneur DynamoDB Local

Infrastructure

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK
Terraform

Répertoirepackages/common/constructs
- Répertoiresrc
  - Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur
    …
  - Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Répertoirepackages/common/terraform
- Répertoiresrc
  - Répertoireapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Répertoirecore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

CDK
Terraform

Répertoirepackages/common/constructs/src
- Répertoireapp
  - Répertoiredynamodb
    <name>.ts Infrastructure spécifique à votre table
- Répertoirecore
  - dynamodb.ts Construct générique de table DynamoDB

Architecture

Le projet déployé provisionne la table elle-même, que tout projet auquel il est connecté lit et écrit :

Loading the diagram…

Développement local

Démarrer DynamoDB Local

Le générateur configure une cible dev qui démarre une instance DynamoDB Local et crée la table. Utilisez la cible dev du projet :

pnpm nx dev <project-name>

yarn nx dev <project-name>

npx nx dev <project-name>

bunx nx dev <project-name>

Cela effectue automatiquement :

Télécharge l’image DynamoDB Local (cible pull-image)
Démarre un conteneur
Crée une table locale avec les index définis dans config.json

Modélisation des données

Le projet généré utilise ElectroDB pour la modélisation d’entités type-safe sur une seule table DynamoDB, suivant la conception à table unique de DynamoDB. Ajoutez ou mettez à jour les fichiers d’entités sous src/entities/, en utilisant l’exemple d’entité généré comme point de départ.

Exemple de définition d’entité :

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

Pour plus de détails, consultez la documentation des entités ElectroDB.

Utiliser le client DynamoDB

Le fichier src/client.ts généré exporte deux utilitaires clés :

getDynamoDBClient() — retourne un singleton DynamoDBClient en cache. Lorsque LOCAL_DEV=true, se connecte à l’instance DynamoDB Local locale ; sinon crée un client AWS utilisant la chaîne de credentials par défaut.
resolveTableName() — retourne le nom de la table DynamoDB. Lorsque LOCAL_DEV=true, retourne la constante du nom de table locale ; sinon récupère le nom depuis AWS AppConfig en utilisant la variable d’environnement RUNTIME_CONFIG_APP_ID et le met en cache pour les appels suivants.

Arrêter DynamoDB Local

L’arrêt de dev (par exemple avec Ctrl+C) supprime automatiquement le conteneur DynamoDB Local, mais préserve le volume nommé afin que vos données persistent entre les redémarrages.

En raison de limitations dans la gestion des signaux sous Windows, le conteneur n’est pas automatiquement supprimé lorsque dev est arrêté. Vous devrez le supprimer manuellement :

<engine> rm -f <scope>-dynamodb

Remplacez <engine> par votre moteur de conteneurs (docker ou finch) et <scope> par la portée de votre espace de travail Nx (par exemple proj).

Ajouter/Supprimer des index secondaires globaux

Les GSI sont définis dans config.json à la racine du projet sous la clé tableConfig.globalSecondaryIndexes. Ajoutez une entrée pour chaque GSI, en suivant la convention de nommage de conception à table unique pour les clés GSI :

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

Le champ sortKey est optionnel pour les GSI avec clé de hachage uniquement.

Ce fichier de configuration est la source unique de vérité lue par tous les consommateurs :

Développement local — dev lit config.json et crée ou met à jour la table locale pour correspondre à la liste des GSI
CDK — le construct lit config.json au moment de la synthèse, donc les modifications de GSI sont reflétées lors du prochain cdk deploy
Terraform — le module lit config.json au moment du plan/apply

Un GSI par Déploiement

Se connecter à la table

Dans n’importe quel projet TypeScript, importez les factories d’entités depuis votre package DynamoDB et utilisez-les directement :

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

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

En coulisses, createExampleEntity() appelle resolveTableName() pour récupérer le nom de la table depuis AWS AppConfig au moment de l’exécution.

Déployer votre table

Le générateur DynamoDB crée une infrastructure CDK ou Terraform en fonction de votre iac sélectionné.

CDK
Terraform

Le construct CDK est créé dans common/constructs. Exemple d’utilisation :

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

Cela provisionne une table DynamoDB avec :

pk (clé de partition) et sk (clé de tri), toutes deux de type String
Des index secondaires globaux tels que définis dans config.json
Une facturation à la demande (PAY_PER_REQUEST)
Un chiffrement KMS géré par le client avec rotation automatique des clés
La récupération à un instant dans le passé activée
La protection contre la suppression activée
Le nom de la table enregistré dans Runtime Config sous l’espace de noms dynamodb dans AWS AppConfig

Le module Terraform est créé dans common/terraform. Exemple d’utilisation :

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

Cela provisionne une table DynamoDB avec :

pk (clé de partition) et sk (clé de tri), toutes deux de type String
Des index secondaires globaux tels que définis dans config.json
Une facturation à la demande (PAY_PER_REQUEST)
Un chiffrement KMS géré par le client avec rotation automatique des clés
La récupération à un instant dans le passé activée
La protection contre la suppression activée, plus une garde de cycle de vie prevent_destroy
Le nom de la table enregistré dans Runtime Config sous l’espace de noms dynamodb dans AWS AppConfig

Le module core/runtime-config/appconfig expose l’espace de noms dynamodb par défaut, de sorte que le nom de la table est déployé sans configuration supplémentaire. Si vous passez explicitement namespaces à ce module, conservez dynamodb dans la liste — sinon aucun profil de configuration n’est créé pour celui-ci et le client de table généré ne peut pas résoudre le nom de la table.

Protection contre la suppression

La table est protégée par deux gardes indépendantes, de sorte que la désactivation de l’une seule ne peut pas supprimer vos données :

CDK
Terraform

deletionProtection, appliquée par DynamoDB.
RemovalPolicy.RETAIN, appliquée par CloudFormation, qui laisse la table en place lorsqu’elle est retirée de la stack.

deletion_protection_enabled, appliquée par DynamoDB.
lifecycle { prevent_destroy = true } sur la table dans common/terraform/src/core/dynamodb/dynamodb.tf, appliquée par Terraform, qui fait échouer tout plan qui détruirait la table.

Supprimer la table

Désactivez la protection pour les environnements où la suppression de table est attendue, comme les stacks de développement ou de prévisualisation éphémères.

CDK
Terraform

import { RemovalPolicy } from 'aws-cdk-lib';
import { MyTable } from '@my-scope/common-constructs';

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

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

prevent_destroy doit être un littéral — Terraform ne permet pas de référencer une variable — il ne peut donc pas être désactivé depuis main.tf. Supprimez également le bloc lifecycle de la table dans common/terraform/src/core/dynamodb/dynamodb.tf :

resource "aws_dynamodb_table" "table" {
  # ...

  lifecycle {
    prevent_destroy = true
  }
}

Mode de facturation

La table utilise par défaut la facturation à la demande (PAY_PER_REQUEST). Passez à la capacité provisionnée pour des charges de travail prévisibles à haut débit.

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

Récupération à un instant dans le passé

La récupération à un instant dans le passé est activée par défaut, vous permettant de restaurer la table à n’importe quel moment des 35 derniers jours.

Désactiver la récupération à un instant dans le passé

CDK
Terraform

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
}

Chiffrement

La table est chiffrée avec une clé KMS gérée par le client par défaut, créée automatiquement pour vous. Passez à une clé gérée par AWS, à la clé détenue par AWS, ou apportez votre propre clé KMS, si vous gérez le chiffrement différemment.

Utiliser une clé gérée par AWS

Utilise la clé KMS partagée aws/dynamodb qu’AWS gère en votre nom. Elle est visible dans la console KMS de votre compte et facturée par requête, mais il n’y a pas de clé à créer, faire pivoter ou supprimer.

CDK
Terraform

import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  encryption: TableEncryption.AWS_MANAGED,
});

Choisir AWS_MANAGED signifie que la table n’est plus chiffrée avec une clé gérée par le client, ce qui échoue à la règle CKV_AWS_119 de Checkov. Supprimez-la sur la table :

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

suppressRules(table.table, ['CKV_AWS_119'], 'Using an AWS managed key rather than a customer-managed CMK');

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

Utiliser la clé détenue par AWS

Utilise une clé entièrement détenue et gérée par AWS — gratuite, sans clé visible dans votre compte. L’option la plus simple lorsque vous n’avez pas besoin d’une clé visible par le client ou le compte pour des raisons de conformité.

CDK
Terraform

import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from '@my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  encryption: TableEncryption.DEFAULT,
});

Choisir DEFAULT signifie que la table n’est plus chiffrée avec une clé gérée par le client, ce qui échoue à la règle CKV_AWS_119 de Checkov. Supprimez-la sur la table :

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

suppressRules(table.table, ['CKV_AWS_119'], 'Using the AWS owned key rather than a customer-managed CMK');

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

Passer de CUSTOMER_MANAGED à une autre option

Sur une table déjà déployée, changer encryption de CUSTOMER_MANAGED (vers AWS_MANAGED ou DEFAULT) en un seul terraform apply échoue : Terraform détruit la clé gérée par le client avant de mettre à jour la table, et DynamoDB rejette alors la mise à jour car la clé est déjà en attente de suppression.

Contournez ce problème en mettant à jour le chiffrement de la table directement via l’AWS CLI d’abord, puis en laissant Terraform rattraper son retard et nettoyer la clé orpheline :

# For AWS_MANAGED:
aws dynamodb update-table --table-name <table-name> \
  --sse-specification Enabled=true,SSEType=KMS,KMSMasterKeyId=alias/aws/dynamodb

# For DEFAULT:
aws dynamodb update-table --table-name <table-name> --sse-specification Enabled=false

# Then wait for this to report ENABLED (or for SSEDescription to disappear, for DEFAULT):
aws dynamodb describe-table --table-name <table-name> --query Table.SSEDescription.Status

Ensuite, mettez à jour encryption dans votre configuration Terraform et exécutez terraform apply normalement — Terraform n’a maintenant besoin que de détruire la clé déjà inutilisée, sans rien qui en dépende.

Utiliser votre propre clé KMS

Fournissez une clé gérée par le client existante au lieu d’en faire créer une pour vous. La clé doit déjà accorder au service DynamoDB les permissions dont il a besoin dans sa propre politique de clé.

CDK
Terraform

import { Key } from 'aws-cdk-lib/aws-kms';
import { MyTable } from '@my-scope/common-constructs';

const key = Key.fromKeyArn(this, 'Key', 'arn:aws:kms:us-east-1:111111111111:key/my-key-id');

const table = new MyTable(this, 'Table', {
  encryptionKey: key,
});

module "my_table" {
  source      = "../../common/terraform/src/app/dynamodb/my-table"
  kms_key_arn = "arn:aws:kms:us-east-1:111111111111:key/my-key-id"
}

Rotation de la clé de chiffrement

Lorsque la table crée sa propre clé KMS gérée par le client (par défaut, et uniquement lorsque vous n’avez pas fourni votre propre clé), cette clé a la rotation automatique activée par défaut. Désactivez-la si votre politique de sécurité gère la rotation en externe.

Désactiver la rotation de la clé de chiffrement

CDK
Terraform

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

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

Désactiver la rotation de clé, ou apporter votre propre clé qui ne pivote pas, échoue à la règle CKV_AWS_7 de Checkov. Supprimez-la sur la clé :

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

suppressRules(table.table.encryptionKey!, ['CKV_AWS_7'], 'Key rotation is managed externally');

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

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre workspace. Les connexions suivantes impliquent ce projet :

tRPC API to TypeScript DynamoDBConnecter une API tRPC à une table DynamoDB

Smithy API to TypeScript DynamoDBConnecter une API Smithy à une table DynamoDB

TypeScript Agent to TypeScript DynamoDBConnecter un TypeScript Agent à une table DynamoDB

MCP Server to TypeScript DynamoDBConnecter un TypeScript MCP Server à une table DynamoDB