Database Relazionale Python

Questo generatore crea un nuovo progetto di 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 dichiarativa dello schema, distribuzione automatica delle migrazioni e un client di database.

Utilizzo

Genera un Database Relazionale

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

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 del database iniziale. Il valore predefinito corrisponde al nome del progetto.
framework	sqlmodel	sqlmodel	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 del progetto Nx); installare una volta alla fine.

Output del Generatore

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

• Directory<name>

  • __init__.py Esportazioni del package (get_engine, session_context)
  • connection.py Engine del database e factory di sessione con autenticazione IAM
  • utils.py Configurazione runtime e helper per lo sviluppo locale
  • migration_handler.py Handler Lambda che esegue le migrazioni Alembic durante la distribuzione
  • create_db_user_handler.py Handler Lambda che crea l’utente del database dell’applicazione durante la distribuzione
  • Directorymodels

    • example.py Definizione di tabella SQLModel di esempio
• Directorymigrations

  • versions Script di migrazione generati da Alembic
  • env.py Ambiente Alembic (si connette al database)
  • script.py.mako Template di script di migrazione Alembic
• alembic.ini Configurazione Alembic
• config.json Dettagli di connessione per lo sviluppo locale e chiave di configurazione runtime
• Dockerfile.migration Immagine container per l’handler di migrazione
• Dockerfile.create-db-user Immagine container per l’handler create-db-user
• project.json Configurazione del progetto e target di build

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 Scarica l’immagine container del database
  • start-container.ts Avvia un container di database locale
  • wait-for-postgres-db.ts Attende che il database locale sia pronto (PostgreSQL)
  • wait-for-mysql-db.ts Attende che il database locale sia pronto (MySQL)

Infrastruttura

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorydbs

      • <name>.ts Infrastruttura specifica per il tuo database
  • Directorycore

    • Directoryrdb

      • aurora.ts Costrutto generico per database Aurora

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorydbs

      • Directory<name>

        • <name>.tf Modulo specifico per il tuo database
  • Directorycore

    • Directoryrdb

      • Directoryaurora

        • aurora.tf Modulo generico 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 Disabilitare 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 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 di database, quindi genera una migrazione da tali modifiche del modello.

Modello di esempio:

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

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 di database locale prima dell’esecuzione:

pnpm

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

yarn

yarn nx run <project>:alembic revision --autogenerate -m "describe your change"

npm

npx nx run <project>:alembic revision --autogenerate -m "describe your change"

bun

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

pnpm

pnpm nx run <project>:migrate

yarn

yarn nx run <project>:migrate

npm

npx nx run <project>:migrate

bun

bunx nx run <project>:migrate

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

Applicazione di Migrazioni Esistenti

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

pnpm

pnpm nx run <project>:migrate

yarn

yarn nx run <project>:migrate

npm

npx nx run <project>:migrate

bun

bunx nx run <project>:migrate

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.

pnpm

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

yarn

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

npm

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

bun

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

Arresto del 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.

Windows

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

Connessione al Database

Importa session_context dal tuo package di database e usalo come async context manager 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))).all()

Il client del database automaticamente:

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

Distribuzione del Database

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

CDK

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 effettua il provisioning di un cluster Aurora con RDS Proxy, credenziali amministrative, utente del database dell’applicazione, registrazione della configurazione runtime e gestore delle migrazioni.

L’infrastruttura generata crea due utenti del database:

• Utente amministratore - Creato durante il provisioning del cluster con credenziali archiviate 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

Terraform

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

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
}

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

L’infrastruttura generata crea due utenti del database:

• Utente amministratore - Creato durante il provisioning del cluster con credenziali archiviate 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 a 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.

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
}

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

Configurazione RDS Proxy

L’infrastruttura generata include un RDS Proxy per impostazione predefinita, che si posiziona tra l’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 della creazione di 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

Costo Aggiuntivo

RDS Proxy è abilitato per impostazione predefinita ma comporta costi aggiuntivi oltre al costo del cluster Aurora. Consulta i prezzi di AWS RDS Proxy per i dettagli. Se preferisci disabilitare il proxy, consulta la sezione seguente.

Disabilitare RDS Proxy

Puoi disabilitare il proxy RDS come segue:

CDK

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, l’applicazione si connette direttamente all’endpoint del cluster Aurora.

Terraform

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

packages/infra/src/main.tf

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

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

Requisiti SSL per la Connessione Senza RDS Proxy

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

Runtime Container

Amazon Linux

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/pki/ca-trust/source/anchors/global-bundle.pem
RUN update-ca-trust

Debian

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
RUN update-ca-certificates

Funzioni Lambda Zip

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

Quando utilizzi RDS Proxy, non è necessario configurare il bundle CA RDS nel runtime che si connette al database.

Istanze del Cluster

Configura le istanze writer e reader per il tuo 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

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

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
}

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, è consigliabile 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

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

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 da cancellazioni accidentali.

Disabilitare la Protezione dalla Cancellazione

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

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
}

Policy di Rimozione

Il costrutto CDK mantiene il cluster Aurora per impostazione predefinita (removalPolicy: RemovalPolicy.RETAIN). Modifica questa impostazione 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

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

Perdita di Dati

RemovalPolicy.DESTROY cancellerà permanentemente tutti i dati quando lo stack viene eliminato. Utilizzare solo in ambienti effimeri (come test automatizzati). Utilizzare RETAIN o SNAPSHOT per tutti gli stack persistenti e di produzione per prevenire la perdita di dati.

Terraform

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 per un ambiente effimero:

packages/infra/src/main.tf

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

frastructure>

Logging e Monitoraggio

Performance Insights è abilitato di default sull’istanza writer di Aurora (crittografato con la chiave KMS del cluster). Puoi anche esportare i log del motore Aurora su CloudWatch Logs (postgresql per Aurora PostgreSQL; audit, error, general e slowquery per Aurora MySQL). Abilita l’esportazione dei log per database:

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
}

Rotazione della Chiave di Crittografia

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

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
}

Connessioni

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

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

FastAPI to Relational DatabaseConnect a FastAPI to an Aurora relational database

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