Salta ai contenuti
@aws/nx-plugin
Blog

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

Sezione intitolata “Utilizzo”

Generare un Database Relazionale

Sezione intitolata “Generare un Database Relazionale”

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

Esegui questo generatore@aws/nx-plugin:ts#rdb

pnpm nx g @aws/nx-plugin:ts#rdb
Componi il tuo comando10

Obbligatorio

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Sezione intitolata “Opzioni”
Opzioni del generatore10 opzioni
nameObbligatoriostring

Nome del progetto database da generare

directorystringPredefinito: packages

La directory in cui memorizzare l'applicazione.

infraenumPredefinito: aurora

Servizio di database relazionale da fornire.

auroranone
engineenumPredefinito: postgres

Motore di database da utilizzare con il servizio selezionato.

postgresmysql
frameworkenumPredefinito: prisma

Framework ORM da utilizzare per il progetto generato.

prisma
iacenumPredefinito: inherit

Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

inheritcdkterraform
subDirectorystring

La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.

databaseUserstringPredefinito: dbadmin

Nome utente amministratore del database. Il valore predefinito è 'dbadmin'.

databaseNamestring

Nome iniziale del database. Il valore predefinito corrisponde al nome del progetto.

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

Sezione intitolata “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
  • .trivyignore Vulnerability IDs to suppress when scanning the migration image
  • 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
  • README.md Project readme
  • rolldown.config.ts Bundler configuration invoked by the bundle target
  • tsconfig.json TypeScript project references
  • tsconfig.lib.json TypeScript configuration for the library build
  • tsconfig.spec.json TypeScript configuration for tests
  • vitest.config.mts Vitest configuration

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

Sezione intitolata “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:

  • 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/constructs/src
    • Directoryapp
      • Directorydbs
        • <name>.ts Infrastruttura specifica per il tuo database
    • Directorycore
      • Directoryrdb
        • aurora.ts Costrutto generico per database Aurora

Architettura

Sezione intitolata “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.

Loading the diagram…

Sviluppo Locale

Sezione intitolata “Sviluppo Locale”

Modellazione dei Dati

Sezione intitolata “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:

packages/postgres/prisma/models/user.prisma
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

Sezione intitolata “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:

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

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

Terminal window
pnpm 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

Sezione intitolata “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:

Terminal window
pnpm nx run <project>:prisma migrate dev

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

Terminal window
pnpm 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

Sezione intitolata “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.

Terminal window
pnpm 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

Sezione intitolata “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.

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

Usare Prisma Studio

Sezione intitolata “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:

Terminal window
pnpm nx run <project>:prisma studio

Arrestare il Database Locale

Sezione intitolata “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.

Connettersi al Database

Sezione intitolata “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

Sezione intitolata “Distribuire il Database”

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

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

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

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

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

Sezione intitolata “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. La scansione non è memorizzata in cache, poiché l’immagine che legge risiede nel motore container anziché su disco — quindi scansiona sempre l’immagine reale e fallisce in modo evidente anziché riportare un successo memorizzato in cache per un’immagine che non è più presente. Ogni esecuzione richiede quindi decine di secondi per immagine e aggiorna il database delle vulnerabilità di Trivy, quindi necessita di accesso alla rete. Lo script root trivy fornito scansiona ogni immagine nel workspace:

Terminal window
pnpm trivy

Soppressione dei Risultati di Trivy

Sezione intitolata “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):

.trivyignore
# 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

Sezione intitolata “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

Sezione intitolata “Disabilitare RDS Proxy”

Puoi disabilitare il proxy RDS come segue:

packages/infra/src/stacks/application-stack.ts
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.

Requisiti SSL per la Connessione Senza RDS Proxy

Sezione intitolata “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
Sezione intitolata “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.

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
Funzioni Lambda Zippate
Sezione intitolata “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:

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

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

Sezione intitolata “Istanze del Cluster”

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

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

Capacità Serverless

Sezione intitolata “Capacità Serverless”

Controlla i limiti di scalabilità di Aurora Serverless v2 per adattarli al tuo carico di lavoro. Entrambi i provider utilizzano per impostazione predefinita un minimo di 0,5 ACU e un massimo di 4.

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

Versione del Motore

Sezione intitolata “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.

engine = postgres
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,
});
engine = mysql
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,
});

Protezione dalla Cancellazione

Sezione intitolata “Protezione dalla Cancellazione”

Il cluster Aurora è protetto da due protezioni indipendenti, in modo che disattivarne una sola non possa eliminare i tuoi dati:

  • deletionProtection, applicata da RDS.
  • RemovalPolicy.RETAIN, applicata da CloudFormation, che lascia il cluster al suo posto quando viene rimosso dallo stack.

Eliminare il Database

Sezione intitolata “Eliminare il Database”

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

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

Politica di Rimozione

Sezione intitolata “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.

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

Per un ambiente effimero in cui il database dovrebbe essere eliminato con lo 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,
});

Logging e Monitoraggio

Sezione intitolata “Logging e Monitoraggio”
engine = postgres

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.

engine = mysql

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.

Il volume dei log esportati — e quindi il costo di ingestione di CloudWatch Logs — scala con le modifiche allo schema e le connessioni piuttosto che con il traffico delle query, poiché i tipi di log che contengono il testo completo delle istruzioni sono esclusi. Su Aurora MySQL l’evento di audit CONNECT viene emesso per ogni connessione, quindi i carichi di lavoro che aprono una connessione per richiesta ne producono di più rispetto a quelli che utilizzano il pooling.

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

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

Rotazione della Chiave di Crittografia

Sezione intitolata “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.

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

Credenziali di Amministrazione

Sezione intitolata “Credenziali di Amministrazione”

La password dell’utente amministratore (master) di Aurora viene generata e ruotata da Aurora stesso in AWS Secrets Manager, utilizzando password utente master gestite da RDS. Il codice dell’infrastruttura non riceve mai la password, quindi non può finire in un template CloudFormation o in un file di stato Terraform. Aurora ruota il segreto ogni 7 giorni senza alcuna funzione di rotazione da distribuire o mantenere.

Il segreto è crittografato con la stessa chiave KMS gestita dal cliente del cluster.

La tua applicazione non utilizza mai queste credenziali. Si connette come utente del database con privilegi minimi utilizzando l’autenticazione IAM — solo i gestori di migrazione e create-db-user leggono il segreto di amministrazione, e a ciascuno viene concesso l’accesso solo a quel segreto e alla sua chiave KMS.

Il segreto di amministrazione è esposto come secret.secretArn sul cluster sottostante, e grantSecretRead concede a un consumatore l’accesso in lettura ad esso:

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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


db.grantSecretRead(myFunction);

Limitazioni

Sezione intitolata “Limitazioni”
engine = mysql

MySQL: Modalità Streaming di API Gateway

Sezione intitolata “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:

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

MySQL: Scadenza del Token IAM

Sezione intitolata “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

Sezione intitolata “Connessioni”

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

tRPCAmazon Aurora
tRPC API to Relational DatabaseConnect a tRPC API to an Aurora relational database
SmithyAmazon Aurora
Smithy API to Relational DatabaseConnect a Smithy API to an Aurora relational database
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database
Model Context ProtocolAmazon Aurora
MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database