Banco de Dados Relacional TypeScript

Este gerador cria um novo projeto de banco de dados relacional apoiado por Amazon Aurora (PostgreSQL ou MySQL) e Prisma ORM. 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ções e um cliente ORM com segurança de tipos.

Uso

Gerar um Banco de Dados Relacional

Você pode gerar um novo projeto de banco de dados relacional de duas maneiras:

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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 - ts#rdb
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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	prisma	prisma	Framework ORM a ser usado para o projeto gerado.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, isso é 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 executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

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

• Directoryprisma

  • Directorymodels

    • example.prisma Example model definition
  • schema.prisma Main Prisma schema (references models)
• Directorysrc

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

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

Infraestrutura

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

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

CDK

• 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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos 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 genérico Aurora

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 Prisma ORM para definir seu esquema de banco de dados e gerar um cliente com segurança de tipos. O fluxo de trabalho é model-first: adicione ou atualize arquivos de modelo Prisma no diretório prisma/models/ do seu projeto de banco de dados, depois gere uma migração a partir dessas alterações de modelo.

Exemplo de modelo User:

packages/postgres/prisma/models/user.prisma

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

Para mais detalhes, consulte o guia oficial de modelagem de dados do Prisma.

Gerando o Cliente do Banco de Dados

O gerador configura automaticamente o target generate para criar um cliente Prisma TypeScript com segurança de tipos sempre que você compilar o projeto. O cliente é escrito em generated/prisma (adicionado ao .gitignore).

Você também pode gerar manualmente o cliente a qualquer momento:

pnpm

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

yarn

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

npm

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

bun

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

Use o target prisma para executar comandos da CLI do Prisma a partir da raiz do workspace:

pnpm

pnpm nx run <project>:prisma generate

yarn

yarn nx run <project>:prisma generate

npm

npx nx run <project>:prisma generate

bun

bunx nx run <project>:prisma generate

O wrapper de runtime em src/prisma.ts exporta:

• getPrisma() - carrega as configurações de conexão do banco de dados do AWS AppConfig e cria um cliente Prisma usando autenticação IAM

O cliente 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 AWS RDS Signer para autenticação IAM
• Gerencia conexões SSL/TLS com validação de certificado
• Lida com pooling de conexões através de pools de conexão de banco de dados persistentes

Criando Migrações

Depois de adicionar ou atualizar modelos em prisma/models/, use migrate dev para gerar arquivos de migração e aplicá-los ao seu banco de dados local ao mesmo tempo.

O target prisma gerado inicia automaticamente um contêiner de banco de dados local antes de executar:

pnpm

pnpm nx run <project>:prisma migrate dev

yarn

yarn nx run <project>:prisma migrate dev

npm

npx nx run <project>:prisma migrate dev

bun

bunx nx run <project>:prisma migrate dev

Se você quiser apenas gerar os arquivos de migração sem aplicá-los ao banco de dados local, adicione --create-only:

pnpm

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

yarn

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

npm

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

bun

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

Isso gera uma nova pasta de migração em prisma/migrations cada vez que seu esquema muda:

• Directoryprisma

  • Directorymigrations

    • Directory20260405013911_initial_migrations

      • migration.sql
    • migration_lock.toml
  • schema.prisma

Quando você implanta a stack AWS, a infraestrutura gerada aplica automaticamente as migrações geradas ao banco de dados implantado.

Aplicando Migrações Existentes

Quando você obtém arquivos de migração criados por outros desenvolvedores, use migrate deploy para aplicar essas migrações existentes ao seu banco de dados local.

pnpm

pnpm nx run <project>:prisma migrate deploy

yarn

yarn nx run <project>:prisma migrate deploy

npm

npx nx run <project>:prisma migrate deploy

bun

bunx nx run <project>:prisma migrate deploy

Neste fluxo de desenvolvimento local, migrate deploy aplica os arquivos de migração ao seu banco de dados local; ele não implanta o banco de dados na AWS.

Executando Comandos do Prisma

O target prisma gerado expõe a CLI do Prisma, para que você possa usá-la para executar qualquer comando suportado pelo Prisma no banco de dados local. Consulte a referência da CLI do Prisma para comandos disponíveis.

pnpm

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

yarn

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

npm

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

bun

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

Usando o Prisma Studio

Prisma Studio é um editor visual para seu banco de dados local. Use-o para navegar por tabelas, inspecionar e editar registros, filtrar dados, seguir relações e executar SQL bruto através do console SQL integrado. É útil para verificar migrações e popular dados de teste durante o desenvolvimento. Inicie-o com:

pnpm

pnpm nx run <project>:prisma studio

yarn

yarn nx run <project>:prisma studio

npm

npx nx run <project>:prisma studio

bun

bunx nx run <project>:prisma studio

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

Em qualquer projeto TypeScript, importe getPrisma do seu pacote de banco de dados e chame-o para obter um cliente Prisma com segurança de tipos:

import { getPrisma } from '@my-scope/db';

const prisma = await getPrisma();
const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });

getPrisma() retorna um cliente inicializado preguiçosamente e em cache. Chamadas subsequentes dentro do mesmo contexto de execução do Lambda reutilizam o pool de conexões existente em vez de abrir um novo.

O cliente Prisma expõe modelos totalmente tipados derivados do seu esquema prisma/models/, fornecendo segurança de tipos de ponta a ponta do banco de dados até a resposta da sua API.

getPrisma() busca as configurações de conexão do banco de dados do AWS AppConfig em tempo de execução.

Configuração em tempo de execução

Isso depende da variável de ambiente RUNTIME_CONFIG_APP_ID para buscar a configuração do AWS AppConfig em tempo de execução. Projetos construídos com este plugin (APIs, Agents, servidores MCP) já têm essa variável configurada automaticamente. Para outros projetos, certifique-se de que RUNTIME_CONFIG_APP_ID esteja definida no ambiente de execução com o ID do aplicativo AppConfig provisionado pela sua infraestrutura. Para mais informações, consulte o guia de Configuração em Tempo de Execução.

Implantando seu Banco de Dados

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

CDK

O construto 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 um 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"

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

  tags = local.common_tags
}

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.

O módulo de banco de dados registra seus detalhes de conexão sob o namespace de configuração de runtime database. Inclua este namespace ao instanciar a aplicação AppConfig de configuração de runtime compartilhada:

packages/infra/src/main.tf

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

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

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

Clique aqui para um exemplo de configuração de VPC.

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.

Verificação de Imagem

A imagem Docker construída para este projeto pode ser verificada em busca de vulnerabilidades usando Trivy, executando a partir da imagem Trivy hospedada no ECR.

Um target trivy é adicionado ao seu projeto que verifica a imagem construída e sai com código diferente de zero se alguma vulnerabilidade de severidade HIGH ou CRITICAL for encontrada. O Dockerfile gerado usa uma imagem base sem vulnerabilidades corrigíveis conhecidas dessas severidades no momento da geração, e atualiza as ferramentas incluídas (como npm) para mantê-lo assim.

A verificação usa o mesmo mecanismo de contêiner que sua construção de imagem (docker ou finch), portanto nenhuma ferramenta adicional é necessária. Como a verificação só é executada novamente quando a imagem muda, uma imagem inalterada não é verificada novamente. O script raiz trivy fornecido verifica todas as imagens no workspace:

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Execute o Trivy no CI

A verificação intencionalmente não está conectada ao build, pois isso pode introduzir atrito desnecessário ao iterar durante o desenvolvimento, já que o banco de dados de vulnerabilidades do Trivy é continuamente atualizado com novos CVEs.

Em vez disso, recomendamos executar o comando acima como uma etapa dedicada em seu pipeline de CI antes da implantação em ambientes de produção.

Vulnerabilidades não corrigíveis são ignoradas

A verificação é executada com --ignore-unfixed, portanto vulnerabilidades sem uma correção disponível não falham a construção, pois não podem ser resolvidas atualizando ferramentas em seu Dockerfile — elas não são relatadas na saída da verificação da construção. À medida que novas vulnerabilidades são divulgadas, o resultado das verificações pode mudar ao longo do tempo, então revise a imagem periodicamente executando trivy image <your-image> sem a flag, e reconstrua contra uma imagem base mais recente (ou adicione etapas de contêiner para aplicar patches disponíveis) assim que uma correção for publicada.

Suprimindo Descobertas do Trivy

Pode haver casos em que você deseja suprimir uma vulnerabilidade específica, por exemplo, quando nenhuma correção está disponível ainda e você avaliou o risco como aceitável.

Adicione o ID da vulnerabilidade (um por linha) ao arquivo .trivyignore na raiz do seu projeto (ou seja, ao lado do seu project.json):

.trivyignore

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

Para mais detalhes sobre filtragem de descobertas, consulte a documentação de filtragem do Trivy.

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:

• Pooling 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 o 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

Ao conectar diretamente ao cluster Aurora (sem RDS Proxy), o runtime que chama getPrisma() deve confiar no pacote de CA do Amazon RDS. O cliente Prisma gerado habilita a verificação de certificado; como você disponibiliza o pacote de CA depende do runtime que se conecta ao banco de dados.

Para Amazon RDS, use o pacote de CA global de:

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

Imagens de Contêiner de Runtime

Se você preparar sua própria imagem de contêiner para o runtime, baixe o pacote de CA do RDS no seu Dockerfile e adicione-o ao armazenamento de confiança do sistema operacional.

Amazon Linux

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

Debian

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
    rm -rf /var/lib/apt/lists/* && \
    curl -fsSL "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" \
    -o /usr/local/share/ca-certificates/rds-bundle.crt && \
    update-ca-certificates

Funções Lambda Zipadas

Para funções Lambda zipadas usando runtimes Node.js 20 ou posterior, carregue o pacote de CA do Amazon RDS definindo NODE_EXTRA_CA_CERTS:

CDK

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

Terraform

packages/infra/src/main.tf

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

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

Para mais detalhes, consulte os requisitos SSL/TLS do AWS Lambda para conexões Amazon RDS. Ao usar RDS Proxy, você não precisa configurar o pacote de CA do RDS no runtime que se conecta ao banco de dados.

Instâncias do Cluster

Configure as instâncias de escritor e leitor 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 do 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 versão 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 contra 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 construto CDK retém o cluster Aurora por padrão (removalPolicy: RemovalPolicy.RETAIN). Altere isso quando você quiser que a exclusão da stack CDK faça 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,
});

Perda de Dados

RemovalPolicy.DESTROY apagará permanentemente todos os dados quando a stack for excluída. Use apenas em ambientes efêmeros (como testes automatizados). Use RETAIN ou SNAPSHOT para todas as stacks persistentes e de produção para evitar perda de dados.

Terraform

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

engine = postgres

O log postgresql é exportado para Aurora PostgreSQL, com registro limitado apenas a instruções DDL (log_statement=ddl), de modo que os valores dos parâmetros das instruções nunca são registrados — desde que cada instrução seja enviada individualmente. log_statement=ddl registra todo o texto bruto de um lote de múltiplas instruções (por exemplo, uma única chamada psql -c "a;b;c") literalmente se qualquer instrução nele for DDL, incluindo quaisquer valores DML nesse mesmo lote.

engine = mysql

Os logs audit e error são exportados para Aurora MySQL — general e slowquery são deliberadamente excluídos, pois registram o texto completo das instruções, incluindo valores DML. Advanced Auditing tem escopo limitado a conexões e DDL (server_audit_events=CONNECT,QUERY_DDL), portanto, os valores dos parâmetros das instruções nunca são registrados.

O Performance Insights está habilitado na instância de gravação do Aurora por padrão (criptografado com a chave KMS do cluster). Os logs do mecanismo Aurora também são exportados para o CloudWatch Logs por padrão, configurados para exibir atividade no nível de esquema sem vazar dados de linha.

Desabilite a exportação de logs por banco de dados se não for necessário:

CDK

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

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

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

Terraform

packages/infra/src/main.tf

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

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
}

Limitações

engine = mysql

MySQL: Modo de Streaming do API Gateway

Ao usar Aurora MySQL com respostas de streaming do API Gateway (por exemplo, com httpBatchStreamLink do tRPC), o cliente MySQL do Prisma mantém o loop de eventos do Node.js após a conclusão de uma consulta, impedindo que o Lambda libere o stream e encerre a solicitação.

Para contornar isso, desconecte explicitamente o cliente em um bloco finally após cada consulta para que o loop de eventos fique livre para sair e a resposta de streaming possa ser concluída.

Opção 1: por procedimento

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

Opção 2: middleware tRPC

Se você estiver usando o padrão de middleware, adicione a chamada $disconnect() ao middleware para que todos os procedimentos construídos sobre ele sejam cobertos 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();
    }
  });
};

Nota

Isso não é necessário para PostgreSQL. O adaptador PostgreSQL usa um pool de conexões pg configurado com allowExitOnIdle: true, que permite que o loop de eventos saia naturalmente sem uma desconexão explícita. Devido a essa limitação, getPrisma() para MySQL não armazena em cache o cliente ou reutiliza conexões entre invocações Lambda quentes. Uma nova conexão é aberta em cada chamada, ao contrário do adaptador PostgreSQL que armazena em cache o cliente no nível do módulo e reutiliza o mesmo pool de conexões.

MySQL: Expiração do Token IAM

Tokens de autenticação IAM do RDS expiram após 15 minutos. O cliente Prisma MySQL captura o token IAM como um valor estático no momento em que getPrisma() é chamado. Uma conexão aberta existente não é afetada, mas se uma nova conexão precisar ser estabelecida após o token ter expirado, a autenticação falhará. O adaptador PostgreSQL evita isso atualizando o token dinamicamente cada vez que o pool abre uma nova conexão, mas o adaptador MySQL não possui mecanismo equivalente.

Cuidado

Tenha cuidado com tarefas que duram mais de 15 minutos. Se o cliente MySQL precisar abrir uma nova conexão após o token IAM original ter expirado, a autenticação falhará.

Para tarefas de longa duração, como trabalhos em lote ou migrações de dados, chame getPrisma() no início de cada unidade de trabalho em vez de uma vez para toda a operação. Como getPrisma() sempre cria um cliente novo e busca um novo token IAM para MySQL, isso garante que cada conexão autentique com um token válido.

Conexões

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

API tRPC para Banco de Dados RelacionalConectar uma API tRPC a um banco de dados relacional Aurora

API Smithy para Banco de Dados RelacionalConectar uma API Smithy a um banco de dados relacional Aurora

Agente TypeScript para Banco de Dados RelacionalConectar um Agente TypeScript a um banco de dados relacional Aurora

Servidor MCP para Banco de Dados RelacionalConectar um Servidor MCP TypeScript a um banco de dados relacional Aurora