Base de données relationnelle TypeScript

Ce générateur crée un nouveau projet de base de données relationnelle basé sur Amazon Aurora (PostgreSQL ou MySQL) et Prisma ORM. Il génère le code d’application et l’infrastructure nécessaires pour provisionner et gérer une base de données en utilisant AWS CDK ou Terraform, avec une définition de schéma déclarative, un déploiement automatique des migrations et un client ORM type-safe.

Utilisation

Générer une base de données relationnelle

Vous pouvez générer un nouveau projet de base de données relationnelle de deux manières :

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

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

yarn

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

npm

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

bun

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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Nom du projet de base de données à générer
directory	string	packages	Le répertoire dans lequel stocker l'application.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
infra	aurora | none	aurora	Service de base de données relationnelle à provisionner.
engine	postgres | mysql	postgres	Moteur de base de données à utiliser avec le service sélectionné.
databaseUser	string	dbadmin	Nom d'utilisateur administrateur de la base de données. Par défaut 'dbadmin'.
databaseName	string	-	Nom initial de la base de données. Par défaut, le nom du projet.
framework	prisma	prisma	Framework ORM à utiliser pour le projet généré.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.
preferInstallDependencies	boolean	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éera la structure de projet suivante dans le répertoire <directory>/<name> :

• Répertoireprisma

  • Répertoiremodels

    • example.prisma Définition de modèle d’exemple
  • schema.prisma Schéma Prisma principal (référence les modèles)
• Répertoiresrc

  • index.ts Point d’entrée du projet
  • prisma.ts Wrapper du client Prisma d’exécution
  • utils.ts Helpers de configuration d’exécution et de secrets
  • create-db-user-handler.ts Gestionnaire Lambda utilisé pour créer l’utilisateur de base de données d’application pendant le déploiement
  • migration-handler.ts Gestionnaire Lambda utilisé pour exécuter les migrations de base de données pendant le déploiement
• .gitignore Entrées d’ignorance Git incluant la sortie du client Prisma généré
• config.json Détails de connexion pour le développement local et clé de configuration d’exécution
• Dockerfile Définition de l’image conteneur pour le gestionnaire de migration
• project.json Configuration du projet et cibles de build
• prisma.config.ts Configuration pour Prisma CLI

Les scripts de développement local sont partagés entre tous les projets de base de données et générés dans packages/common/scripts/ :

• Répertoirepackages/common/scripts/src/rdb

  • pull-image.ts Télécharge l’image de conteneur de la base de données
  • start-container.ts Démarre un conteneur de base de données local
  • wait-for-postgres-db.ts Attend que la base de données locale soit prête (PostgreSQL)
  • wait-for-mysql-db.ts Attend que la base de données locale soit prête (MySQL)

Infrastructure

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Modules Terraform pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoiredbs

      • <name>.ts Infrastructure spécifique à votre base de données
  • Répertoirecore

    • Répertoirerdb

      • aurora.ts Construction générique de base de données Aurora

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiredbs

      • Répertoire<name>

        • <name>.tf Module spécifique à votre base de données
  • Répertoirecore

    • Répertoirerdb

      • Répertoireaurora

        • aurora.tf Module Aurora générique

Architecture

La base de données déployée a l’architecture suivante. Par défaut, un Amazon RDS Proxy se trouve devant le cluster Aurora pour mettre en commun les connexions et pour activer l’authentification IAM — voir Désactiver RDS Proxy pour l’alternative. L’architecture est la même que vous sélectionniez le moteur PostgreSQL ou MySQL ; seule la variante du moteur Aurora diffère.

Développement local

Modélisation des données

Le projet généré utilise Prisma ORM pour définir votre schéma de base de données et générer un client type-safe. Le flux de travail est axé sur le modèle : ajoutez ou mettez à jour les fichiers de modèle Prisma dans le répertoire prisma/models/ de votre projet de base de données, puis générez une migration à partir de ces modifications de modèle.

Exemple de modèle User :

packages/postgres/prisma/models/user.prisma

model User {
  id          Int      @id @default(autoincrement())
  firstName   String
  lastName    String
}

Pour plus de détails, consultez le guide officiel sur la modélisation des données avec Prisma.

Générer le client de base de données

Le générateur configure automatiquement la cible generate pour créer un client Prisma TypeScript type-safe chaque fois que vous construisez le projet. Le client est écrit dans generated/prisma (ajouté à .gitignore).

Vous pouvez également générer manuellement le client à tout moment :

pnpm

pnpm nx generate <your-db-project-name>

yarn

yarn nx generate <your-db-project-name>

npm

npx nx generate <your-db-project-name>

bun

bunx nx generate <your-db-project-name>

Utilisez la cible prisma pour exécuter les commandes CLI Prisma depuis la racine de l’espace de travail :

pnpm

pnpm nx run <project>:prisma generate

yarn

yarn nx run <project>:prisma generate

npm

npx nx run <project>:prisma generate

bun

bunx nx run <project>:prisma generate

Le wrapper d’exécution dans src/prisma.ts exporte :

• getPrisma() - charge les paramètres de connexion à la base de données depuis AWS AppConfig et crée un client Prisma utilisant l’authentification IAM

Le client automatiquement :

• Récupère la configuration de la base de données depuis AWS AppConfig en utilisant la variable d’environnement RUNTIME_CONFIG_APP_ID
• Génère des jetons d’authentification temporaires via AWS RDS Signer pour l’authentification IAM
• Gère les connexions SSL/TLS avec validation de certificat
• Gère le pooling de connexions via des pools de connexions de base de données persistants

Créer des migrations

Après avoir ajouté ou mis à jour des modèles sous prisma/models/, utilisez migrate dev pour générer les fichiers de migration et les appliquer à votre base de données locale en même temps.

La cible prisma générée démarre automatiquement un conteneur de base de données locale avant l’exécution :

pnpm

pnpm nx run <project>:prisma migrate dev

yarn

yarn nx run <project>:prisma migrate dev

npm

npx nx run <project>:prisma migrate dev

bun

bunx nx run <project>:prisma migrate dev

Si vous souhaitez uniquement générer les fichiers de migration sans les appliquer à la base de données locale, ajoutez --create-only :

pnpm

pnpm nx run <project>:prisma migrate dev --create-only

yarn

yarn nx run <project>:prisma migrate dev --create-only

npm

npx nx run <project>:prisma migrate dev --create-only

bun

bunx nx run <project>:prisma migrate dev --create-only

Cela génère un nouveau dossier de migration dans prisma/migrations chaque fois que votre schéma change :

• Répertoireprisma

  • Répertoiremigrations

    • Répertoire20260405013911_initial_migrations

      • migration.sql
    • migration_lock.toml
  • schema.prisma

Lorsque vous déployez la stack AWS, l’infrastructure générée applique automatiquement les migrations générées à la base de données déployée.

Appliquer les migrations existantes

Lorsque vous récupérez des fichiers de migration créés par d’autres développeurs, utilisez migrate deploy pour appliquer ces migrations existantes à votre base de données locale.

pnpm

pnpm nx run <project>:prisma migrate deploy

yarn

yarn nx run <project>:prisma migrate deploy

npm

npx nx run <project>:prisma migrate deploy

bun

bunx nx run <project>:prisma migrate deploy

Dans ce flux de développement local, migrate deploy applique les fichiers de migration à votre base de données locale ; il ne déploie pas la base de données sur AWS.

Exécuter les commandes Prisma

La cible prisma générée expose la CLI Prisma, vous pouvez donc l’utiliser pour exécuter n’importe quelle commande prise en charge par Prisma contre la base de données locale. Consultez la référence CLI Prisma pour les commandes disponibles.

pnpm

pnpm nx run <project>:prisma <prisma-command>

yarn

yarn nx run <project>:prisma <prisma-command>

npm

npx nx run <project>:prisma <prisma-command>

bun

bunx nx run <project>:prisma <prisma-command>

Utiliser Prisma Studio

Prisma Studio est un éditeur visuel pour votre base de données locale. Utilisez-le pour parcourir les tables, inspecter et modifier les enregistrements, filtrer les données, suivre les relations et exécuter du SQL brut via la console SQL intégrée. Il est utile pour vérifier les migrations et alimenter les données de test pendant le développement. Lancez-le avec :

pnpm

pnpm nx run <project>:prisma studio

yarn

yarn nx run <project>:prisma studio

npm

npx nx run <project>:prisma studio

bun

bunx nx run <project>:prisma studio

Arrêter la base de données locale

Arrêter dev (par exemple avec Ctrl+C) supprime automatiquement le conteneur de base de données local, mais préserve le volume nommé afin que vos données persistent entre les redémarrages.

Windows

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

<engine> rm -f <scope>-<db-name>

Remplacez <engine> par votre moteur de conteneurs (docker ou finch), <scope> par le scope de votre workspace Nx (par ex. proj), et <db-name> par le nom de votre projet de base de données (par ex. my-db).

Connexion à la base de données

Dans n’importe quel projet TypeScript, importez getPrisma depuis votre package de base de données et appelez-le pour obtenir un client Prisma type-safe :

import { getPrisma } from ':my-scope/db';

const prisma = await getPrisma();
const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });

getPrisma() retourne un client initialisé de manière paresseuse et mis en cache. Les appels suivants dans le même contexte d’exécution Lambda réutilisent le pool de connexions existant plutôt que d’en ouvrir un nouveau.

Le client Prisma expose des modèles entièrement typés dérivés de votre schéma prisma/models/, vous offrant une sécurité de type de bout en bout depuis la base de données jusqu’à votre réponse API.

Déployer votre base de données

Le générateur de base de données relationnelle crée une infrastructure CDK ou Terraform en fonction de votre iacProvider sélectionné.

CDK

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

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

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

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    ...
    const db = new MyDatabase(this, 'Db', {
      vpc,
      vpcSubnets: {
        subnetType: SubnetType.PRIVATE_ISOLATED,
      }
    });
  }
}

Cela provisionne un cluster Aurora avec RDS Proxy, des identifiants administrateur, un utilisateur de base de données d’application, l’enregistrement de la configuration d’exécution et un gestionnaire de migration.

L’infrastructure générée crée deux utilisateurs de base de données :

• Utilisateur administrateur - Créé lors du provisionnement du cluster avec des identifiants stockés dans AWS Secrets Manager
• Utilisateur d’application - Créé via une ressource personnalisée Lambda avec l’authentification IAM activée et des privilèges DML (SELECT, INSERT, UPDATE, DELETE) sur la base de données d’application

Terraform

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

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"

  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
  lambda_subnet_ids   = module.vpc.private_subnet_ids

  tags = local.common_tags
}

Cela provisionne un cluster Aurora avec RDS Proxy, des identifiants administrateur, une Lambda create-db-user, l’enregistrement de la configuration d’exécution, une Lambda de migration et des ressources de registre de conteneurs.

L’infrastructure générée crée deux utilisateurs de base de données :

• Utilisateur administrateur - Créé lors du provisionnement du cluster avec des identifiants stockés dans AWS Secrets Manager
• Utilisateur d’application - Créé via une fonction Lambda avec l’authentification IAM activée et des privilèges DML (SELECT, INSERT, UPDATE, DELETE) sur la base de données d’application

L’utilisateur d’application est automatiquement créé avec un nom aléatoire et l’authentification IAM. Le client de base de données généré est déjà configuré pour s’authentifier en tant que cet utilisateur en utilisant des jetons RDS de courte durée, de sorte que votre code d’application ne gère jamais les mots de passe de base de données.

Votre VPC doit inclure des sous-réseaux publics, des sous-réseaux privés avec sortie et des sous-réseaux privés isolés. La base de données peut s’exécuter dans des sous-réseaux privés isolés, tandis que les fonctions Lambda d’application doivent s’exécuter dans des sous-réseaux privés avec sortie afin qu’elles puissent atteindre les services AWS tels qu’AppConfig.

CDK

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

const vpc = new Vpc(this, 'Vpc', {
  subnetConfiguration: [
    {
      name: 'public',
      subnetType: SubnetType.PUBLIC,
    },
    {
      name: 'private_with_egress',
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      name: 'private_isolated',
      subnetType: SubnetType.PRIVATE_ISOLATED,
    },
  ],
});

Terraform

packages/infra/src/main.tf

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 6.0"

  name = "app"
  ...
  public_subnet_names  = ["public"]
  private_subnet_names = ["private_with_egress"]
  intra_subnet_names   = ["private_isolated"]

  enable_nat_gateway = true
  single_nat_gateway = true
}

Utilisez le générateur connection pour connecter un projet à cette base de données — consultez le guide de connexion pour le type de calcul approprié (par exemple FastAPI, serveur MCP, agent) pour le câblage d’infrastructure requis pour l’atteindre.

Analyse d’image

L’image Docker construite pour ce projet est analysée pour détecter les vulnérabilités dans le cadre de la construction en utilisant Trivy, exécuté à partir de l’image Trivy hébergée sur ECR.

Une cible trivy est ajoutée à votre projet qui analyse l’image construite et fait échouer la construction si une vulnérabilité de gravité HIGH ou CRITICAL est trouvée. Le Dockerfile généré utilise une image de base sans vulnérabilité corrigeable connue de ces gravités au moment de la génération, et met à niveau les outils intégrés (tels que npm) pour le maintenir ainsi.

L’analyse utilise le même moteur de conteneur que votre construction d’image (docker ou finch), donc aucun outillage supplémentaire n’est requis. Étant donné que l’analyse n’est réexécutée que lorsque l’image change, une image inchangée n’est pas réanalysée.

Les vulnérabilités non corrigeables sont ignorées

L’analyse s’exécute avec --ignore-unfixed, donc les vulnérabilités sans correctif disponible ne font pas échouer la construction, car elles ne peuvent pas être corrigées en mettant à niveau les outils dans votre Dockerfile — elles ne sont pas signalées dans la sortie d’analyse de la construction. Au fur et à mesure que de nouvelles vulnérabilités sont divulguées, le résultat des analyses peut changer au fil du temps, donc examinez l’image périodiquement en exécutant trivy image <your-image> sans le flag, et reconstruisez avec une image de base plus récente (ou ajoutez des étapes de conteneur pour appliquer les correctifs disponibles) une fois qu’un correctif est publié.

Suppression des résultats Trivy

Il peut y avoir des cas où vous souhaitez supprimer une vulnérabilité spécifique, par exemple lorsqu’aucun correctif n’est encore disponible et que vous avez évalué le risque comme acceptable.

Ajoutez l’ID de vulnérabilité (un par ligne) au fichier .trivyignore à la racine de votre projet :

.trivyignore

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Pour plus de détails sur le filtrage des résultats, consultez la documentation de filtrage Trivy.

Configuration RDS Proxy

L’infrastructure générée inclut un RDS Proxy par défaut, qui se situe entre votre application et le cluster Aurora. RDS Proxy offre plusieurs avantages :

• Mise en commun des connexions - Maintient un pool de connexions à la base de données qui peuvent être partagées entre les instances d’application, réduisant ainsi la surcharge liée à l’établissement de nouvelles connexions
• Résilience des connexions - Gère automatiquement les basculements et les reconnexions lors des remplacements d’instances Aurora ou de la maintenance
• Authentification IAM - Prend en charge l’authentification de base de données basée sur IAM, éliminant le besoin de gérer les identifiants de base de données dans le code de votre application
• Sécurité améliorée - Applique le chiffrement TLS pour toutes les connexions

Coût supplémentaire

RDS Proxy est activé par défaut mais entraîne des frais supplémentaires en plus du coût du cluster Aurora. Consultez la tarification AWS RDS Proxy pour plus de détails. Si vous préférez désactiver le proxy, consultez la section ci-dessous.

Désactiver RDS Proxy

Vous pouvez désactiver le proxy RDS comme suit :

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableRdsProxy: false,
});

Lorsque RDS Proxy est désactivé, votre application se connecte directement au point de terminaison du cluster Aurora.

Terraform

Par défaut, RDS Proxy est activé. Vous pouvez le désactiver si nécessaire :

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_rds_proxy = false
}

Lorsque RDS Proxy est désactivé, votre application se connecte directement au point de terminaison du cluster Aurora.

Exigences SSL lors de la connexion sans RDS Proxy

Lors de la connexion directe au cluster Aurora (sans RDS Proxy), le runtime qui appelle getPrisma() doit faire confiance au bundle CA Amazon RDS. Le client Prisma généré active la vérification des certificats ; la manière dont vous rendez le bundle CA disponible dépend du runtime qui se connecte à la base de données.

Pour Amazon RDS, utilisez le bundle CA global depuis :

https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

Images de conteneur d’exécution

Si vous préparez votre propre image de conteneur pour le runtime, téléchargez le bundle CA RDS dans votre Dockerfile et ajoutez-le au magasin de confiance du système d’exploitation.

Amazon Linux

RUN curl -fsSL "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" \
    -o /etc/pki/ca-trust/source/anchors/rds-bundle.pem && \
    update-ca-trust

Debian

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
    rm -rf /var/lib/apt/lists/* && \
    curl -fsSL "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" \
    -o /usr/local/share/ca-certificates/rds-bundle.crt && \
    update-ca-certificates

Fonctions Lambda compressées

Pour les fonctions Lambda compressées utilisant les runtimes Node.js 20 ou ultérieurs, chargez le bundle CA Amazon RDS en définissant NODE_EXTRA_CA_CERTS :

CDK

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

const api = new Api(this, 'Api', {
  integrations: Api.defaultIntegrations(this)
    .withDefaultOptions({
      environment: {
        NODE_EXTRA_CA_CERTS: '/var/runtime/ca-cert.pem',
      },
    })
    .build(),
});

Terraform

packages/infra/src/main.tf

module "api" {
  source = "..."
  ...

  environment_variables = {
    NODE_EXTRA_CA_CERTS = "/var/runtime/ca-cert.pem"
  }
}

Pour plus de détails, consultez les exigences SSL/TLS pour les connexions Amazon RDS d’AWS Lambda. Lors de l’utilisation de RDS Proxy, vous n’avez pas besoin de configurer le bundle CA RDS dans le runtime qui se connecte à la base de données.

Instances du cluster

Configurez les instances d’écriture et de lecture pour votre cluster Aurora.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  writer: ClusterInstance.serverlessV2('writer'),
  readers: [ClusterInstance.serverlessV2('reader')],
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  instance_count = 2  # 1 writer + 1 reader
}

Capacité Serverless

Contrôlez les limites de mise à l’échelle d’Aurora Serverless v2 pour correspondre à votre charge de travail.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  serverlessV2MinCapacity: 0.5,
  serverlessV2MaxCapacity: 8,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  serverless_min_capacity = 0.5
  serverless_max_capacity = 8
}

Version du moteur

Épinglez une version spécifique du moteur Aurora.

Par défaut, l’image de conteneur de base de données locale générée correspond à la version par défaut du moteur Aurora. Si vous modifiez la version du moteur Aurora, il est recommandé d’utiliser également une version d’image de conteneur locale correspondante pour une compatibilité maximale. Consultez les notes de version AWS pour les versions Aurora PostgreSQL et les versions Aurora MySQL pour identifier la version de base de données communautaire correspondante.

L’image de base de données locale est configurée dans le champ localDev.image du fichier config.json généré à la racine de votre projet de base de données. Mettez à jour cette valeur lorsque vous changez de version de moteur.

engine = postgres

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraPostgresEngineVersion.VER_17_7,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  engine_version = "17.7"
}

engine = mysql

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraMysqlEngineVersion.VER_3_12_0,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  engine_version = "8.0.mysql_aurora.3.12.0"
}

Protection contre la suppression

La protection contre la suppression est activée par défaut (deletionProtection: true dans CDK, deletion_protection = true dans Terraform) pour protéger le cluster Aurora contre toute suppression accidentelle.

Désactiver la protection contre la suppression

Vous pouvez désactiver la protection contre la suppression pour les environnements où la suppression de la base de données est attendue, comme les stacks de développement ou de prévisualisation éphémères.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  deletionProtection: false,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  deletion_protection = false
}

Politique de suppression

Le construct CDK conserve le cluster Aurora par défaut (removalPolicy: RemovalPolicy.RETAIN). Modifiez ceci lorsque vous souhaitez que la suppression de la stack CDK crée un snapshot ou détruise le cluster à la place.

Lors de l’utilisation de RemovalPolicy.DESTROY, la protection contre la suppression doit également être désactivée avant que le cluster puisse être supprimé.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  removalPolicy: RemovalPolicy.SNAPSHOT,
});

Pour un environnement éphémère où la base de données doit être supprimée avec la stack :

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  deletionProtection: false,
  removalPolicy: RemovalPolicy.DESTROY,
});

Terraform

Terraform n’utilise pas les politiques de suppression CDK. Par défaut, le module crée un snapshot final lors de la suppression (skip_final_snapshot = false). Pour ignorer le snapshot final pour un environnement éphémère :

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  deletion_protection = false
  skip_final_snapshot = true
}

Perte de données

skip_final_snapshot = true effacera définitivement toutes les données lorsque le cluster sera supprimé. À utiliser uniquement dans des environnements éphémères (tels que les tests automatisés). Conservez skip_final_snapshot = false pour toutes les stacks persistantes et de production afin d’éviter la perte de données.

Journalisation et surveillance

Performance Insights est activé par défaut sur l’instance d’écriture Aurora (chiffré avec la clé KMS du cluster). Vous pouvez également exporter les journaux du moteur Aurora vers CloudWatch Logs (postgresql pour Aurora PostgreSQL ; audit, error, general et slowquery pour Aurora MySQL). Activez l’export des journaux par base de données :

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableCloudwatchLogs: true,
  enablePerformanceInsights: false, // disable if not required
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_cloudwatch_logs      = true
  enable_performance_insights = false # disable if not required
}

Rotation de clé de chiffrement

La clé KMS utilisée pour chiffrer le cluster Aurora et son secret d’identifiants a la rotation automatique des clés activée par défaut. Désactivez-la si votre politique de sécurité gère la rotation en externe.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableKeyRotation: false,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_key_rotation = false
}

Limitations

engine = mysql

MySQL : Mode de streaming API Gateway

Lors de l’utilisation d’Aurora MySQL avec des réponses en streaming API Gateway (par exemple avec le httpBatchStreamLink de tRPC), le client MySQL Prisma conserve la boucle d’événements Node.js après la fin d’une requête, empêchant le Lambda de vider le flux et de terminer la requête.

Pour contourner ce problème, déconnectez explicitement le client dans un bloc finally après chaque requête afin que la boucle d’événements soit libre de se terminer et que la réponse en streaming puisse se terminer.

Option 1 : par procédure

export const listExampleTable = publicProcedure
  .output(z.array(ExampleTableSchema))
  .query(async () => {
    const prisma = await getPrisma();
    try {
      return await prisma.exampleTable.findMany();
    } finally {
      await prisma.$disconnect();
    }
  });

Option 2 : middleware tRPC

Si vous utilisez le modèle de middleware, ajoutez l’appel $disconnect() au middleware afin que toutes les procédures construites dessus soient couvertes automatiquement :

packages/api/src/middleware/db.ts

import { getPrisma } from ':my-scope/db';
import { initTRPC } from '@trpc/server';

export interface IDbContext {
  db: Awaited<ReturnType<typeof getPrisma>>;
}

export const createDbPlugin = () => {
  const t = initTRPC.context<IDbContext>().create();
  return t.procedure.use(async (opts) => {
    const db = await getPrisma();
    try {
      return await opts.next({
        ctx: {
          ...opts.ctx,
          db,
        },
      });
    } finally {
      await db.$disconnect();
    }
  });
};

Note

Ceci n’est pas requis pour PostgreSQL. L’adaptateur PostgreSQL utilise un pool de connexions pg configuré avec allowExitOnIdle: true, ce qui permet à la boucle d’événements de se terminer naturellement sans déconnexion explicite. En raison de cette limitation, getPrisma() pour MySQL ne met pas en cache le client ni ne réutilise les connexions entre les invocations Lambda chaudes. Une nouvelle connexion est ouverte à chaque appel, contrairement à l’adaptateur PostgreSQL qui met en cache le client au niveau du module et réutilise le même pool de connexions.

MySQL : Expiration du jeton IAM

Les jetons d’authentification IAM RDS expirent après 15 minutes. Le client MySQL Prisma capture le jeton IAM comme une valeur statique au moment où getPrisma() est appelé. Une connexion ouverte existante n’est pas affectée, mais si une nouvelle connexion doit être établie après l’expiration du jeton, l’authentification échouera. L’adaptateur PostgreSQL évite cela en rafraîchissant le jeton dynamiquement chaque fois que le pool ouvre une nouvelle connexion, mais l’adaptateur MySQL n’a pas de mécanisme équivalent.

Attention

Soyez prudent avec les tâches s’exécutant plus de 15 minutes. Si le client MySQL doit ouvrir une nouvelle connexion après l’expiration du jeton IAM d’origine, l’authentification échouera.

Pour les tâches de longue durée telles que les travaux par lots ou les migrations de données, appelez getPrisma() au début de chaque unité de travail plutôt qu’une fois pour l’ensemble de l’opération. Parce que getPrisma() crée toujours un nouveau client et récupère un nouveau jeton IAM pour MySQL, cela garantit que chaque connexion s’authentifie avec un jeton valide.

Connexions

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

API tRPC vers Base de données relationnelleConnecter une API tRPC à une base de données relationnelle Aurora

API Smithy vers Base de données relationnelleConnecter une API Smithy à une base de données relationnelle Aurora

TypeScript Agent vers Base de données relationnelleConnecter un TypeScript Agent à une base de données relationnelle Aurora

Serveur MCP vers Base de données relationnelleConnecter un serveur MCP TypeScript à une base de données relationnelle Aurora