Banco de Dados Relacional Python

Este gerador cria um novo projeto de banco de dados relacional Python apoiado pelo Amazon Aurora (PostgreSQL ou MySQL), SQLModel para modelagem de dados e Alembic para migrações de esquema. Ele gera o código da aplicação e a infraestrutura necessária para provisionar e gerenciar um banco de dados usando AWS CDK ou Terraform, com definição de esquema declarativa, implantação automática de migração e um cliente de banco de dados.

Uso

Gerar um Banco de Dados Relacional

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - py#rdb
5. Preencha os parâmetros obrigatórios
6. Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	Nome do projeto de banco de dados a ser gerado
directory	string	packages	O diretório onde armazenar a aplicação.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
infra	aurora | none	aurora	Serviço de banco de dados relacional a ser provisionado.
engine	postgres | mysql	postgres	Motor de banco de dados a ser usado com o serviço selecionado.
databaseUser	string	dbadmin	Nome de usuário do administrador do banco de dados. O padrão é 'dbadmin'.
databaseName	string	-	Nome inicial do banco de dados. O padrão é o nome do projeto.
framework	sqlmodel	sqlmodel	Framework ORM a ser usado para o projeto gerado.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, este é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao agrupar múltiplos geradores (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projeto Nx); instale uma vez no final.

Saída do Gerador

O gerador cria a seguinte estrutura de projeto no diretório <directory>/<name>:

• Directory<name>

  • __init__.py Exportações do pacote (get_engine, session_context)
  • connection.py Motor de banco de dados e fábrica de sessão com autenticação IAM
  • utils.py Configuração de tempo de execução e auxiliares de desenvolvimento local
  • migration_handler.py Manipulador Lambda que executa migrações Alembic durante a implantação
  • create_db_user_handler.py Manipulador Lambda que cria o usuário do banco de dados da aplicação durante a implantação
  • Directorymodels

    • example.py Definição de tabela SQLModel de exemplo
• Directorymigrations

  • versions Scripts de migração gerados pelo Alembic
  • env.py Ambiente Alembic (conecta ao banco de dados)
  • script.py.mako Modelo de script de migração Alembic
• alembic.ini Configuração do Alembic
• config.json Detalhes de conexão de desenvolvimento local e chave de configuração de tempo de execução
• Dockerfile.migration Imagem de contêiner para o manipulador de migração
• Dockerfile.create-db-user Imagem de contêiner para o manipulador create-db-user
• project.json Configuração do projeto e alvos de build

Os scripts de desenvolvimento local são compartilhados entre todos os projetos de banco de dados e gerados em packages/common/scripts/:

• Directorypackages/common/scripts/src/rdb

  • pull-image.ts Baixa a imagem de contêiner do banco de dados
  • start-container.ts Inicia um contêiner de banco de dados local
  • wait-for-postgres-db.ts Aguarda o banco de dados local estar pronto (PostgreSQL)
  • wait-for-mysql-db.ts Aguarda o banco de dados local estar pronto (MySQL)

Infraestrutura

Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

O projeto comum de infraestrutura como código está estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorydbs

      • <name>.ts Infraestrutura específica para seu banco de dados
  • Directorycore

    • Directoryrdb

      • aurora.ts Construto genérico de banco de dados Aurora

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorydbs

      • Directory<name>

        • <name>.tf Módulo específico para seu banco de dados
  • Directorycore

    • Directoryrdb

      • Directoryaurora

        • aurora.tf Módulo Aurora genérico

Arquitetura

O banco de dados implantado possui a seguinte arquitetura. Por padrão, um Amazon RDS Proxy fica na frente do cluster Aurora para agrupar conexões e habilitar autenticação IAM — veja Desabilitar RDS Proxy para a alternativa. A arquitetura é a mesma independentemente de você selecionar o mecanismo PostgreSQL ou MySQL; apenas o tipo de mecanismo Aurora difere.

Desenvolvimento Local

Modelagem de Dados

O projeto gerado usa SQLModel para definir o esquema do seu banco de dados. O fluxo de trabalho é model-first: adicione ou atualize classes de tabela SQLModel no diretório <name>/models/ do seu projeto de banco de dados e, em seguida, gere uma migração a partir dessas alterações de modelo.

Exemplo de modelo:

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

Importe seus modelos em <name>/models/__init__.py para que o Alembic possa descobri-los durante a autogeração.

Criando Migrações

Após adicionar ou atualizar modelos, use o Alembic para gerar e aplicar scripts de migração. O alvo alembic gerado inicia automaticamente um contêiner de banco de dados local antes de executar:

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"

Isso gera um novo script de migração em migrations/versions/. Revise o script gerado antes de aplicá-lo.

Aplique a migração ao seu banco de dados local:

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 você implantar a pilha AWS, a infraestrutura gerada aplica automaticamente as migrações geradas ao banco de dados implantado.

Aplicando Migrações Existentes

Quando você baixar arquivos de migração criados por outros desenvolvedores, aplique-os ao seu banco de dados local:

pnpm

pnpm nx run <project>:migrate

yarn

yarn nx run <project>:migrate

npm

npx nx run <project>:migrate

bun

bunx nx run <project>:migrate

Executando Comandos Alembic

O alvo alembic gerado expõe a CLI do Alembic, para que você possa executar qualquer comando Alembic no banco de dados local. Consulte a referência de comandos do Alembic para comandos disponíveis.

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>

Parando o Banco de Dados Local

Parar dev (por exemplo, com Ctrl+C) remove automaticamente o contêiner do banco de dados local, mas preserva o volume nomeado para que seus dados persistam entre reinicializações.

Windows

Devido a limitações no tratamento de sinais no Windows, o contêiner não é removido automaticamente quando dev é parado. Você precisará removê-lo manualmente:

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

Substitua <engine> pelo seu motor de contêiner (docker ou finch), <scope> pelo escopo do seu workspace Nx (por exemplo, proj) e <db-name> pelo nome do seu projeto de banco de dados (por exemplo, my-db).

Conectando ao Banco de Dados

Importe session_context do seu pacote de banco de dados e use-o como um gerenciador de contexto assíncrono para obter uma 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()

O cliente de banco de dados automaticamente:

• Recupera a configuração do banco de dados do AWS AppConfig usando a variável de ambiente RUNTIME_CONFIG_APP_ID
• Gera tokens de autenticação temporários via boto3 RDS Signer para autenticação IAM
• Estabelece conexões TLS usando ssl.create_default_context()

Implantando seu Banco de Dados

O gerador de banco de dados relacional cria infraestrutura CDK ou Terraform com base no seu iacProvider selecionado.

CDK

O construtor CDK é criado em common/constructs. Exemplo de uso:

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

Isso provisiona um cluster Aurora com RDS Proxy, credenciais de administrador, usuário de banco de dados da aplicação, registro de configuração de runtime e manipulador de migração.

A infraestrutura gerada cria dois usuários de banco de dados:

• Usuário administrador - Criado durante o provisionamento do cluster com credenciais armazenadas no AWS Secrets Manager
• Usuário da aplicação - Criado via recurso personalizado Lambda com autenticação IAM habilitada e privilégios DML (SELECT, INSERT, UPDATE, DELETE) no banco de dados da aplicação

Terraform

O módulo Terraform é criado em common/terraform. Exemplo de uso:

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
}

Isso provisiona um cluster Aurora com RDS Proxy, credenciais de administrador, Lambda create-db-user, registro de configuração de runtime, Lambda de migração e recursos de registro de contêiner.

A infraestrutura gerada cria dois usuários de banco de dados:

• Usuário administrador - Criado durante o provisionamento do cluster com credenciais armazenadas no AWS Secrets Manager
• Usuário da aplicação - Criado via função Lambda com autenticação IAM habilitada e privilégios DML (SELECT, INSERT, UPDATE, DELETE) no banco de dados da aplicação

O usuário da aplicação é criado automaticamente com um nome aleatório e autenticação IAM. O cliente de banco de dados gerado já está configurado para autenticar como este usuário usando tokens RDS de curta duração, então o código da sua aplicação nunca manipula senhas de banco de dados.

Sua VPC deve incluir sub-redes públicas, sub-redes privadas com saída e sub-redes privadas isoladas. O banco de dados pode ser executado em sub-redes privadas isoladas, enquanto as funções Lambda da aplicação devem ser executadas em sub-redes privadas com saída para que possam alcançar serviços AWS como 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
}

Use o gerador connection para conectar um projeto a este banco de dados — consulte o guia de conexão para o tipo de computação relevante (por exemplo, FastAPI, servidor MCP, agente) para a configuração de infraestrutura necessária para alcançá-lo.

Configuração do RDS Proxy

A infraestrutura gerada inclui um RDS Proxy por padrão, que fica entre sua aplicação e o cluster Aurora. O RDS Proxy oferece vários benefícios:

• Pool de conexões - Mantém um pool de conexões de banco de dados que podem ser compartilhadas entre instâncias da aplicação, reduzindo a sobrecarga de estabelecer novas conexões
• Resiliência de conexão - Lida automaticamente com failovers e reconexões durante substituições de instâncias Aurora ou manutenção
• Autenticação IAM - Suporta autenticação de banco de dados baseada em IAM, eliminando a necessidade de gerenciar credenciais de banco de dados no código da sua aplicação
• Segurança aprimorada - Impõe criptografia TLS para todas as conexões

Custo Adicional

O RDS Proxy está habilitado por padrão, mas incorre em cobranças adicionais além do custo do cluster Aurora. Consulte preços do AWS RDS Proxy para detalhes. Se você preferir desabilitar o proxy, consulte a seção abaixo.

Desabilitar RDS Proxy

Você pode desabilitar o proxy RDS da seguinte forma:

CDK

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

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

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

Quando o RDS Proxy está desabilitado, sua aplicação se conecta diretamente ao endpoint do cluster Aurora.

Terraform

Por padrão, o RDS Proxy está habilitado. Você pode desabilitá-lo se necessário:

packages/infra/src/main.tf

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

Quando o RDS Proxy está desabilitado, sua aplicação se conecta diretamente ao endpoint do cluster Aurora.

Requisitos SSL ao Conectar Sem RDS Proxy

O pacote CA do Amazon RDS deve estar no armazenamento de confiança do sistema do tempo de execução.

Tempos de Execução de Contêiner

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

Funções Lambda Zip

Para funções Lambda implantadas como zip (como uma py#api FastAPI), o armazenamento de confiança CA integrado do ambiente de execução Lambda do Amazon Linux 2023 inclui as CAs raiz da Amazon usadas pelo RDS.

Ao usar RDS Proxy, você não precisa configurar o pacote CA do RDS no tempo de execução que se conecta ao banco de dados.

Instâncias de Cluster

Configure as instâncias de gravação e leitura para o seu 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
}

Capacidade Serverless

Controle os limites de escalabilidade do Aurora Serverless v2 para corresponder à sua carga de trabalho.

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
}

Versão do Motor

Fixe uma versão específica do motor Aurora.

Por padrão, a imagem do contêiner de banco de dados local gerada corresponde à versão padrão do motor Aurora. Se você alterar a versão do motor Aurora, é recomendável também usar uma versão de imagem de contêiner local correspondente para máxima compatibilidade. Consulte as notas de lançamento da AWS para versões do Aurora PostgreSQL e versões do Aurora MySQL para identificar a versão correspondente do banco de dados da comunidade.

A imagem do banco de dados local é configurada no campo localDev.image do arquivo config.json gerado na raiz do seu projeto de banco de dados. Atualize esse valor quando você alterar as versões do motor.

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

Proteção contra Exclusão

A proteção contra exclusão está habilitada por padrão (deletionProtection: true no CDK, deletion_protection = true no Terraform) para proteger o cluster Aurora de exclusão acidental.

Desabilitar Proteção contra Exclusão

Você pode desabilitar a proteção contra exclusão para ambientes onde a exclusão do banco de dados é esperada, como stacks de desenvolvimento ou preview de curta duração.

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
}

Política de Remoção

O construtor CDK retém o cluster Aurora por padrão (removalPolicy: RemovalPolicy.RETAIN). Altere isso quando você quiser que a exclusão da stack CDK crie um snapshot ou destrua o cluster.

Ao usar RemovalPolicy.DESTROY, a proteção contra exclusão também deve ser desabilitada antes que o cluster possa ser excluído.

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

Para um ambiente efêmero onde o banco de dados deve ser excluído com a stack:

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

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

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

Terraform

O Terraform não usa políticas de remoção do CDK. Por padrão, o módulo cria um snapshot final na exclusão (skip_final_snapshot = false). Para pular o snapshot final em um ambiente efêmero:

packages/infra/src/main.tf

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

Perda de Dados

skip_final_snapshot = true apagará permanentemente todos os dados quando o cluster for excluído. Use apenas em ambientes efêmeros (como testes automatizados). Mantenha skip_final_snapshot = false para todas as stacks persistentes e de produção para evitar perda de dados.

Registro e Monitoramento

O Performance Insights está habilitado na instância de gravação do Aurora por padrão (criptografado com a chave KMS do cluster). Você também pode exportar os logs do mecanismo Aurora para o CloudWatch Logs (postgresql para Aurora PostgreSQL; audit, error, general e slowquery para Aurora MySQL). Habilite a exportação de logs por banco de dados:

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
}

Rotação de Chave de Criptografia

A chave KMS usada para criptografar o cluster Aurora e seu segredo de credenciais tem a rotação automática de chave habilitada por padrão. Desabilite-a se sua política de segurança gerenciar a rotação externamente.

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
}

Conexões

Use o gerador connection para integrar este projeto com outros no seu workspace. As seguintes conexões envolvem este projeto:

Python Agent para Banco de Dados RelacionalConectar um Python Agent a um banco de dados relacional Aurora

FastAPI para Banco de Dados RelacionalConectar um FastAPI a um banco de dados relacional Aurora

Python MCP Server para Banco de Dados RelacionalConectar um Python MCP Server a um banco de dados relacional Aurora