Salta ai contenuti
@aws/nx-plugin
Blog

Database Relazionale Python

Questo generatore crea un nuovo progetto database relazionale Python supportato da Amazon Aurora (PostgreSQL o MySQL), SQLModel per la modellazione dei dati e Alembic per le migrazioni dello schema. Genera il codice dell’applicazione e l’infrastruttura necessari per il provisioning e la gestione di un database utilizzando AWS CDK o Terraform, con definizione dello schema dichiarativa, distribuzione automatica delle migrazioni e un client database.

Utilizzo

Sezione intitolata “Utilizzo”

Genera un Database Relazionale

Sezione intitolata “Genera un Database Relazionale”

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

pnpm nx g @aws/nx-plugin:py#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: sqlmodel

Framework ORM da utilizzare per il progetto generato.

sqlmodel
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 del database iniziale. 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 del progetto Nx); installare una volta alla fine.

Output del Generatore

Sezione intitolata “Output del Generatore”

Il generatore crea la seguente struttura di progetto nella directory <directory>/<name>:

  • Directory<name>
    • __init__.py Package exports
    • connection.py Database engine and session factory with IAM authentication
    • utils.py Runtime config and local development helpers
    • migration_handler.py Lambda handler that runs Alembic migrations during deployment
    • create_db_user_handler.py Lambda handler that creates the application database user during deployment
    • Directorymodels
      • __init__.py Model exports, imported by Alembic to discover your tables
      • example.py Example SQLModel table definition
  • Directorymigrations
    • versions Alembic-generated migration scripts
    • env.py Alembic environment (connects to the database)
    • script.py.mako Alembic migration script template
  • Directorytests
    • __init__.py Module initialisation
    • conftest.py Test configuration
    • test_noop.py Placeholder test
  • alembic.ini Alembic configuration
  • config.json Local development connection details and runtime config key
  • Dockerfile.migration Container image for the migration handler
  • Dockerfile.create-db-user Container image for the create-db-user handler
  • project.json Project configuration and build targets
  • pyproject.toml Packaging configuration file used by UV
  • README.md Project README
  • .python-version Contains the project’s Python version
  • .gitignore Files excluded from version control

Gli script di sviluppo locale sono condivisi tra tutti i progetti 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 SQLModel per definire lo schema del database. Il flusso di lavoro è model-first: aggiungi o aggiorna le classi di tabella SQLModel nella directory <name>/models/ del tuo progetto database, quindi genera una migrazione da tali modifiche del modello.

Esempio di modello:

packages/my_db/my_db/models/example.py
from sqlalchemy import Column, String
from sqlmodel import Field, SQLModel




class ExampleModel(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(sa_column=Column(String(255), nullable=False))
    description: str | None = Field(default=None, sa_column=Column(String(255), nullable=True))

Importa i tuoi modelli in <name>/models/__init__.py in modo che Alembic possa scoprirli durante l’autogenerazione.

Creazione di Migrazioni

Sezione intitolata “Creazione di Migrazioni”

Dopo aver aggiunto o aggiornato i modelli, utilizza Alembic per generare e applicare gli script di migrazione. Il target alembic generato avvia automaticamente un container database locale prima dell’esecuzione:

Terminal window
pnpm nx run <project>:alembic revision --autogenerate -m "describe your change"

Questo genera un nuovo script di migrazione in migrations/versions/. Rivedi lo script generato prima di applicarlo.

Applica la migrazione al tuo database locale:

Terminal window
pnpm nx run <project>:migrate

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

Applicazione di Migrazioni Esistenti

Sezione intitolata “Applicazione di Migrazioni Esistenti”

Quando scarichi file di migrazione creati da altri sviluppatori, applicali al tuo database locale:

Terminal window
pnpm nx run <project>:migrate

Esecuzione di Comandi Alembic

Sezione intitolata “Esecuzione di Comandi Alembic”

Il target alembic generato espone la CLI di Alembic, quindi puoi eseguire qualsiasi comando Alembic sul database locale. Consulta il riferimento dei comandi Alembic per i comandi disponibili.

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

Arresto del Database Locale

Sezione intitolata “Arresto del Database Locale”

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

Connessione al Database

Sezione intitolata “Connessione al Database”

Importa session_context dal tuo package database e usalo come gestore di contesto asincrono per ottenere un AsyncSession:

from sqlmodel import select


from my_scope_my_db import session_context
from my_scope_my_db.models.example import ExampleModel


async def example():
    async with session_context() as session:
        results = (await session.execute(select(ExampleModel))).scalars().all()

Il client database automaticamente:

  • Recupera la configurazione del database da AWS AppConfig a runtime
  • Genera token di autenticazione temporanei tramite boto3 RDS Signer per l’autenticazione IAM
  • Stabilisce connessioni TLS utilizzando ssl.create_default_context()

Distribuzione del Database

Sezione intitolata “Distribuzione del 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 RDS Proxy

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

Il bundle CA di Amazon RDS deve essere nel trust store di sistema del runtime.

Runtime Container
Sezione intitolata “Runtime Container”
ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/pki/ca-trust/source/anchors/global-bundle.pem
RUN update-ca-trust
Funzioni Lambda Zip
Sezione intitolata “Funzioni Lambda Zip”

Per le funzioni Lambda distribuite come zip (come una py#api FastAPI), il trust store CA integrato dell’ambiente di esecuzione Lambda Amazon Linux 2023 include le CA Root di Amazon utilizzate da RDS.

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 Admin

Sezione intitolata “Credenziali Admin”

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

Connessioni

Sezione intitolata “Connessioni”

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

Strands AgentsPythonAmazon AuroraPython
Python Agent to Relational DatabaseConnect a Python Agent to an Aurora relational database
FastAPIAmazon AuroraPython
FastAPI to Relational DatabaseConnect a FastAPI to an Aurora relational database
Model Context ProtocolPythonAmazon AuroraPython
Python MCP Server to Relational DatabaseConnect a Python MCP Server to an Aurora relational database