Database Relazionale TypeScript

Questo generatore crea un nuovo progetto di database relazionale supportato da Amazon Aurora (PostgreSQL o MySQL) e Prisma ORM. Genera il codice dell’applicazione e l’infrastruttura necessari per fornire e gestire un database utilizzando AWS CDK o Terraform, con definizione dichiarativa dello schema, distribuzione automatica delle migrazioni e un client ORM type-safe.

Utilizzo

Generare un Database Relazionale

Puoi generare un nuovo progetto di database relazionale in due modi:

CLI
VSCode

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

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

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto database da generare
directory	string	packages	La directory in cui memorizzare l'applicazione.
subDirectory	string	-	La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
infra	aurora \| none	aurora	Servizio di database relazionale da fornire.
engine	postgres \| mysql	postgres	Motore di database da utilizzare con il servizio selezionato.
databaseUser	string	dbadmin	Nome utente amministratore del database. Il valore predefinito è 'dbadmin'.
databaseName	string	-	Nome iniziale del database. Il valore predefinito corrisponde al nome del progetto.
framework	prisma	prisma	Framework ORM da utilizzare per il progetto generato.
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 creerà la seguente struttura di progetto nella directory <directory>/<name>:

Directoryprisma
- Directorymodels
  - example.prisma Example model definition
- schema.prisma Main Prisma schema (references models)
Directorysrc
- index.ts Project entry point
- prisma.ts Prisma runtime client wrapper
- utils.ts Runtime config and secret helpers
- create-db-user-handler.ts Lambda handler used to create the application database user during deployment
- migration-handler.ts Lambda handler used to run database migrations during deployment
.gitignore Git ignore entries including generated Prisma client output
config.json Local development connection details and runtime config key
Dockerfile Container image definition for the migration handler
package.json Project manifest defining the project’s package name and dependencies
project.json Project configuration and build targets
prisma.config.ts Configuration for Prisma CLI

Gli script di sviluppo locale sono condivisi tra tutti i progetti di database e generati in packages/common/scripts/:

Directorypackages/common/scripts/src/rdb
- pull-image.ts Pulls the database container image
- start-container.ts Starts a local database container
- wait-for-postgres-db.ts Waits for the local database to be ready (PostgreSQL)
- wait-for-mysql-db.ts Waits for the local database to be ready (MySQL)

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
Terraform

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

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

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directorydbs
    <name>.ts Infrastruttura specifica per il tuo database
- Directorycore
  - Directoryrdb
    aurora.ts Costrutto generico per database Aurora

Architettura

Il database distribuito ha la seguente architettura. Per impostazione predefinita, un Amazon RDS Proxy si trova davanti al cluster Aurora per raggruppare le connessioni e per abilitare l’autenticazione IAM — vedi Disable RDS Proxy per l’alternativa. L’architettura è la stessa sia che si selezioni il motore PostgreSQL o MySQL; solo il tipo di motore Aurora differisce.

Sviluppo Locale

Modellazione dei Dati

Il progetto generato utilizza Prisma ORM per definire lo schema del database e generare un client type-safe. Il flusso di lavoro è model-first: aggiungi o aggiorna i file del modello Prisma nella directory prisma/models/ del tuo progetto di database, quindi genera una migrazione da tali modifiche del modello.

Esempio di modello User:

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

Per maggiori dettagli, consulta la guida ufficiale alla modellazione dei dati di Prisma.

Generare il Client del Database

Il generatore configura automaticamente il target generate per creare un client Prisma TypeScript type-safe ogni volta che compili il progetto. Il client viene scritto in generated/prisma (aggiunto a .gitignore).

Puoi anche generare manualmente il client in qualsiasi momento:

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

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

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

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

Usa il target prisma per eseguire i comandi della CLI di Prisma dalla radice del workspace:

pnpm nx run <project>:prisma generate

yarn nx run <project>:prisma generate

npx nx run <project>:prisma generate

bunx nx run <project>:prisma generate

Il wrapper runtime in src/prisma.ts esporta:

getPrisma() - carica le impostazioni di connessione al database da AWS AppConfig e crea un client Prisma utilizzando l’autenticazione IAM

Il client automaticamente:

Recupera la configurazione del database da AWS AppConfig utilizzando la variabile d’ambiente RUNTIME_CONFIG_APP_ID
Genera token di autenticazione temporanei tramite AWS RDS Signer per l’autenticazione IAM
Gestisce le connessioni SSL/TLS con validazione del certificato
Gestisce il connection pooling attraverso pool di connessioni al database persistenti

Creare Migrazioni

Dopo aver aggiunto o aggiornato i modelli in prisma/models/, usa migrate dev per generare i file di migrazione e applicarli contemporaneamente al tuo database locale.

Il target prisma generato avvia automaticamente un container di database locale prima dell’esecuzione:

pnpm nx run <project>:prisma migrate dev

yarn nx run <project>:prisma migrate dev

npx nx run <project>:prisma migrate dev

bunx nx run <project>:prisma migrate dev

Se vuoi solo generare i file di migrazione senza applicarli al database locale, aggiungi --create-only:

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

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

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

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

Questo genera una nuova cartella di migrazione in prisma/migrations ogni volta che il tuo schema cambia:

Directoryprisma
- Directorymigrations
  - Directory20260405013911_initial_migrations
    migration.sql
  - migration_lock.toml
- schema.prisma

Quando distribuisci lo stack AWS, l’infrastruttura generata applica automaticamente le migrazioni generate al database distribuito.

Applicare Migrazioni Esistenti

Quando scarichi i file di migrazione creati da altri sviluppatori, usa migrate deploy per applicare quelle migrazioni esistenti al tuo database locale.

pnpm nx run <project>:prisma migrate deploy

yarn nx run <project>:prisma migrate deploy

npx nx run <project>:prisma migrate deploy

bunx nx run <project>:prisma migrate deploy

In questo flusso di sviluppo locale, migrate deploy applica i file di migrazione al tuo database locale; non distribuisce il database su AWS.

Eseguire Comandi Prisma

Il target prisma generato espone la CLI di Prisma, quindi puoi usarla per eseguire qualsiasi comando supportato da Prisma sul database locale. Consulta il riferimento della CLI di Prisma per i comandi disponibili.

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

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

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

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

Usare Prisma Studio

Prisma Studio è un editor visuale per il tuo database locale. Usalo per esplorare le tabelle, ispezionare e modificare i record, filtrare i dati, seguire le relazioni ed eseguire SQL raw tramite la console SQL integrata. È utile per verificare le migrazioni e inserire dati di test durante lo sviluppo. Avvialo con:

pnpm nx run <project>:prisma studio

yarn nx run <project>:prisma studio

npx nx run <project>:prisma studio

bunx nx run <project>:prisma studio

Arrestare il Database Locale

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

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

Sostituisci <engine> con il tuo motore di container (docker o finch), <scope> con lo scope del tuo workspace Nx (ad es. proj) e <db-name> con il nome del tuo progetto di database (ad es. my-db).

Connettersi al Database

In qualsiasi progetto TypeScript, importa getPrisma dal tuo pacchetto di database e chiamalo per ottenere 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() restituisce un client inizializzato in modo lazy e memorizzato nella cache. Le chiamate successive all’interno dello stesso contesto di esecuzione Lambda riutilizzano il pool di connessioni esistente anziché aprirne uno nuovo.

Il client Prisma espone modelli completamente tipizzati derivati dal tuo schema prisma/models/, offrendoti type safety end-to-end dal database fino alla risposta della tua API.

getPrisma() recupera le impostazioni di connessione al database da AWS AppConfig a runtime.

Distribuire il Database

Il generatore di database relazionali crea un’infrastruttura CDK o Terraform in base al tuo iac selezionato.

CDK
Terraform

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

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

Questo esegue il provisioning di un cluster Aurora con RDS Proxy, credenziali amministratore, utente del database dell’applicazione, registrazione della configurazione di runtime e gestore delle migrazioni.

L’infrastruttura generata crea due utenti del database:

Utente amministratore - Creato durante il provisioning del cluster con credenziali memorizzate in AWS Secrets Manager
Utente applicazione - Creato tramite una risorsa personalizzata Lambda con autenticazione IAM abilitata e privilegi DML (SELECT, INSERT, UPDATE, DELETE) sul database dell’applicazione

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

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

  # Database subnets have no internet route; Lambda subnets need NAT egress.
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id

  tags = local.common_tags
}

Questo esegue il provisioning di un cluster Aurora con RDS Proxy, credenziali amministratore, Lambda create-db-user, registrazione della configurazione di runtime, Lambda di migrazione e risorse del registro dei container.

Il modulo del database registra i suoi dettagli di connessione nello spazio dei nomi della configurazione di runtime database. Includi questo spazio dei nomi quando istanzi l’applicazione AppConfig della configurazione di runtime condivisa:

module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database"]
}

L’infrastruttura generata crea due utenti del database:

Utente amministratore - Creato durante il provisioning del cluster con credenziali memorizzate in AWS Secrets Manager
Utente applicazione - Creato tramite una funzione Lambda con autenticazione IAM abilitata e privilegi DML (SELECT, INSERT, UPDATE, DELETE) sul database dell’applicazione

L’utente applicazione viene creato automaticamente con un nome casuale e autenticazione IAM. Il client del database generato è già configurato per autenticarsi come questo utente utilizzando token RDS di breve durata, quindi il codice dell’applicazione non gestisce mai le password del database.

Il tuo VPC dovrebbe includere subnet pubbliche, subnet private con egress e subnet private isolate. Il database può essere eseguito in subnet private isolate, mentre le funzioni Lambda dell’applicazione dovrebbero essere eseguite in subnet private con egress in modo che possano raggiungere i servizi AWS come AppConfig.

Clicca qui per una configurazione VPC di esempio.

Utilizza il generatore connection per connettere un progetto a questo database — consulta la guida alla connessione per il tipo di compute pertinente (ad es. FastAPI, server MCP, agent) per il cablaggio dell’infrastruttura necessario per raggiungerlo.

Scansione delle Immagini

L’immagine Docker costruita per questo progetto può essere scansionata per vulnerabilità utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.

Un target trivy viene aggiunto al tuo progetto che scansiona l’immagine costruita ed esce con codice diverso da zero se viene trovata qualsiasi vulnerabilità di gravità HIGH o CRITICAL. Il Dockerfile generato utilizza un’immagine base senza vulnerabilità risolvibili note di queste gravità al momento della generazione, e aggiorna gli strumenti inclusi (come npm) per mantenerla tale.

La scansione utilizza lo stesso motore container della tua build dell’immagine (docker o finch), quindi non sono richiesti strumenti aggiuntivi. Poiché la scansione viene rieseguita solo quando l’immagine cambia, un’immagine non modificata non viene scansionata nuovamente. Lo script root trivy fornito scansiona ogni immagine nel workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Soppressione dei Risultati di Trivy

Potrebbero esserci casi in cui desideri sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e hai valutato il rischio come accettabile.

Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella root del tuo progetto (cioè accanto al tuo project.json):

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

Per maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.

Configurazione di RDS Proxy

L’infrastruttura generata include un RDS Proxy per impostazione predefinita, che si posiziona tra la tua applicazione e il cluster Aurora. RDS Proxy offre diversi vantaggi:

Connection pooling - Mantiene un pool di connessioni al database che possono essere condivise tra le istanze dell’applicazione, riducendo l’overhead di stabilire nuove connessioni
Resilienza delle connessioni - Gestisce automaticamente i failover e le riconnessioni durante le sostituzioni delle istanze Aurora o la manutenzione
Autenticazione IAM - Supporta l’autenticazione al database basata su IAM, eliminando la necessità di gestire le credenziali del database nel codice dell’applicazione
Sicurezza migliorata - Impone la crittografia TLS per tutte le connessioni

Disabilitare RDS Proxy

Puoi disabilitare il proxy RDS come segue:

CDK
Terraform

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

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

Quando RDS Proxy è disabilitato, la tua applicazione si connette direttamente all’endpoint del cluster Aurora.

Per impostazione predefinita, RDS Proxy è abilitato. Puoi disabilitarlo se necessario:

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

Quando RDS Proxy è disabilitato, la tua applicazione si connette direttamente all’endpoint del cluster Aurora.

Requisiti SSL per la Connessione Senza RDS Proxy

Quando ci si connette direttamente al cluster Aurora (senza RDS Proxy), il runtime che chiama getPrisma() deve fidarsi del bundle CA di Amazon RDS. Il client Prisma generato abilita la verifica del certificato; il modo in cui rendi disponibile il bundle CA dipende dal runtime che si connette al database.

Per Amazon RDS, usa il bundle CA globale da:

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

Immagini Container del Runtime

Se prepari la tua immagine container per il runtime, scarica il bundle CA di RDS nel tuo Dockerfile e aggiungilo al trust store del sistema operativo.

Amazon Linux
Debian

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

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

Funzioni Lambda Zippate

Per le funzioni Lambda zippate che utilizzano runtime Node.js 20 o successivi, carica il bundle CA di Amazon RDS impostando NODE_EXTRA_CA_CERTS:

CDK
Terraform

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

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

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

Per maggiori dettagli, consulta i requisiti SSL/TLS per le connessioni Amazon RDS di AWS Lambda. Quando si utilizza RDS Proxy, non è necessario configurare il bundle CA di RDS nel runtime che si connette al database.

Istanze del Cluster

Configura le istanze writer e reader per il tuo cluster Aurora.

CDK
Terraform

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

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

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

Capacità Serverless

Controlla i limiti di scalabilità di Aurora Serverless v2 per adattarli al tuo carico di lavoro.

CDK
Terraform

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

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

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

Versione del Motore

Fissa una versione specifica del motore Aurora.

Per impostazione predefinita, l’immagine del container del database locale generata corrisponde alla versione predefinita del motore Aurora. Se modifichi la versione del motore Aurora, si consiglia di utilizzare anche una versione dell’immagine del container locale corrispondente per la massima compatibilità. Consulta le note di rilascio AWS per le versioni di Aurora PostgreSQL e le versioni di Aurora MySQL per identificare la versione del database della community corrispondente.

L’immagine del database locale è configurata nel campo localDev.image del file config.json generato nella radice del progetto del database. Aggiorna quel valore quando modifichi le versioni del motore.

CDK
Terraform

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

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

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

CDK
Terraform

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

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

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

Protezione dalla Cancellazione

La protezione dalla cancellazione è abilitata per impostazione predefinita (deletionProtection: true in CDK, deletion_protection = true in Terraform) per proteggere il cluster Aurora dalla cancellazione accidentale.

Disabilitare la Protezione dalla Cancellazione

È possibile disabilitare la protezione dalla cancellazione per ambienti in cui la cancellazione del database è prevista, come stack di sviluppo o di anteprima di breve durata.

CDK
Terraform

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

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

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

Politica di Rimozione

Il costrutto CDK mantiene il cluster Aurora per impostazione predefinita (removalPolicy: RemovalPolicy.RETAIN). Modifica questo comportamento quando desideri che l’eliminazione dello stack CDK crei uno snapshot o distrugga il cluster.

Quando si utilizza RemovalPolicy.DESTROY, la protezione dall’eliminazione deve essere disabilitata prima che il cluster possa essere eliminato.

CDK
Terraform

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

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

Per un ambiente effimero in cui il database dovrebbe essere eliminato con lo stack:

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 non utilizza le politiche di rimozione CDK. Per impostazione predefinita, il modulo crea uno snapshot finale all’eliminazione (skip_final_snapshot = false). Per saltare lo snapshot finale in un ambiente effimero:

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

Logging e Monitoraggio

Il log postgresql viene esportato per Aurora PostgreSQL, con la registrazione limitata alle sole istruzioni DDL (log_statement=ddl) in modo che i valori dei parametri delle istruzioni non vengano mai registrati — purché ogni istruzione venga inviata singolarmente. log_statement=ddl registra l’intero testo grezzo di un batch multi-istruzione (ad esempio una singola chiamata psql -c "a;b;c") testualmente se qualsiasi istruzione in esso è DDL, inclusi eventuali valori DML nello stesso batch.

I log audit ed error vengono esportati per Aurora MySQL — general e slowquery sono deliberatamente esclusi poiché registrano il testo completo delle istruzioni, inclusi i valori DML. Advanced Auditing è limitato alle connessioni e al DDL (server_audit_events=CONNECT,QUERY_DDL), quindi i valori dei parametri delle istruzioni non vengono mai registrati.

Performance Insights è abilitato per impostazione predefinita sull’istanza writer di Aurora (crittografato con la chiave KMS del cluster). Anche i log del motore Aurora vengono esportati in CloudWatch Logs per impostazione predefinita, configurati per mostrare l’attività a livello di schema senza esporre i dati delle righe.

Disabilita l’esportazione dei log per database se non necessaria:

CDK
Terraform

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

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

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

Rotazione della Chiave di Crittografia

La chiave KMS utilizzata per crittografare il cluster Aurora e il suo secret delle credenziali ha la rotazione automatica della chiave abilitata per impostazione predefinita. Disabilitala se la tua politica di sicurezza gestisce la rotazione esternamente.

CDK
Terraform

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

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

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

Limitazioni

MySQL: Modalità Streaming di API Gateway

Quando si utilizza Aurora MySQL con risposte in streaming di API Gateway (ad es. con httpBatchStreamLink di tRPC), il client MySQL di Prisma mantiene il ciclo degli eventi di Node.js dopo il completamento di una query, impedendo alla Lambda di svuotare lo stream e terminare la richiesta.

Per aggirare questo problema, disconnetti esplicitamente il client in un blocco finally dopo ogni query in modo che il ciclo degli eventi sia libero di uscire e la risposta in streaming possa completarsi.

Opzione 1: per procedura

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

Opzione 2: middleware tRPC

Se stai utilizzando il pattern middleware, aggiungi la chiamata $disconnect() al middleware in modo che tutte le procedure costruite su di esso siano coperte automaticamente:

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

MySQL: Scadenza del Token IAM

I token di autenticazione IAM di RDS scadono dopo 15 minuti. Il client Prisma MySQL cattura il token IAM come valore statico al momento della chiamata di getPrisma(). Una connessione aperta esistente non è interessata, ma se è necessario stabilire una nuova connessione dopo la scadenza del token, l’autenticazione fallirà. L’adattatore PostgreSQL evita questo problema aggiornando il token dinamicamente ogni volta che il pool apre una nuova connessione, ma l’adattatore MySQL non ha un meccanismo equivalente.

Per attività di lunga durata come job batch o migrazioni di dati, chiama getPrisma() all’inizio di ogni unità di lavoro anziché una volta per l’intera operazione. Poiché getPrisma() crea sempre un client nuovo e recupera un nuovo token IAM per MySQL, questo garantisce che ogni connessione si autentichi con un token valido.

Connessioni

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

tRPC API to Relational DatabaseConnect a tRPC API to an Aurora relational database

Smithy API to Relational DatabaseConnect a Smithy API to an Aurora relational database

TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database

MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database