Base de Datos Relacional TypeScript

Este generador crea un nuevo proyecto de base de datos relacional respaldado por Amazon Aurora (PostgreSQL o MySQL) y Prisma ORM. Genera el código de aplicación y la infraestructura necesaria para aprovisionar y gestionar una base de datos usando AWS CDK o Terraform, con definición de esquema declarativa, despliegue automático de migraciones y un cliente ORM con tipos seguros.

Uso

Generar una Base de Datos Relacional

Puedes generar un nuevo proyecto de base de datos relacional de dos maneras:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#rdb
5. Complete los parámetros requeridos
6. Haga clic en Generate

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto de base de datos a generar
directory	string	packages	El directorio donde almacenar la aplicación.
subDirectory	string	-	El subdirectorio donde se coloca el proyecto. Por defecto es el nombre del proyecto.
infra	aurora | none	aurora	Servicio de base de datos relacional a provisionar.
engine	postgres | mysql	postgres	Motor de base de datos a utilizar con el servicio seleccionado.
databaseUser	string	dbadmin	Nombre de usuario del administrador de la base de datos. Por defecto es 'dbadmin'.
databaseName	string	-	Nombre inicial de la base de datos. Por defecto es el nombre del proyecto.
framework	prisma	prisma	Framework ORM a utilizar para el proyecto generado.
iac	inherit | cdk | terraform	inherit	El proveedor IaC preferido. Por defecto, se hereda de tu selección inicial.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador creará la siguiente estructura de proyecto en el directorio <directory>/<name>:

• Directorioprisma

  • Directoriomodels

    • example.prisma Definición de modelo de ejemplo
  • schema.prisma Esquema principal de Prisma (referencia modelos)
• Directoriosrc

  • index.ts Punto de entrada del proyecto
  • prisma.ts Envoltorio del cliente Prisma en tiempo de ejecución
  • utils.ts Ayudantes de configuración en tiempo de ejecución y secretos
  • create-db-user-handler.ts Manejador Lambda usado para crear el usuario de base de datos de aplicación durante el despliegue
  • migration-handler.ts Manejador Lambda usado para ejecutar migraciones de base de datos durante el despliegue
• .gitignore Entradas de Git ignore incluyendo la salida del cliente Prisma generado
• config.json Detalles de conexión de desarrollo local y clave de configuración en tiempo de ejecución
• Dockerfile Definición de imagen de contenedor para el manejador de migración
• project.json Configuración del proyecto y objetivos de construcción
• prisma.config.ts Configuración para Prisma CLI

Los scripts de desarrollo local se comparten entre todos los proyectos de base de datos y se generan en packages/common/scripts/:

• Directoriopackages/common/scripts/src/rdb

  • pull-image.ts Descarga la imagen de contenedor de la base de datos
  • start-container.ts Inicia un contenedor de base de datos local
  • wait-for-postgres-db.ts Espera a que la base de datos local esté lista (PostgreSQL)
  • wait-for-mysql-db.ts Espera a que la base de datos local esté lista (MySQL)

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriodbs

      • <name>.ts Infraestructura específica para tu base de datos
  • Directoriocore

    • Directoriordb

      • aurora.ts Construcción genérica de base de datos Aurora

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriodbs

      • Directorio<name>

        • <name>.tf Módulo específico para tu base de datos
  • Directoriocore

    • Directoriordb

      • Directorioaurora

        • aurora.tf Módulo genérico de Aurora

Arquitectura

La base de datos desplegada tiene la siguiente arquitectura. Por defecto, un Amazon RDS Proxy se sitúa frente al clúster Aurora para agrupar conexiones y habilitar la autenticación IAM — consulte Deshabilitar RDS Proxy para la alternativa. La arquitectura es la misma ya sea que seleccione el motor PostgreSQL o MySQL; solo difiere el tipo de motor Aurora.

Desarrollo Local

Modelado de Datos

El proyecto generado usa Prisma ORM para definir tu esquema de base de datos y generar un cliente con tipos seguros. El flujo de trabajo es model-first: agrega o actualiza archivos de modelo Prisma bajo el directorio prisma/models/ de tu proyecto de base de datos, luego genera una migración a partir de esos cambios de modelo.

Ejemplo de modelo User:

packages/postgres/prisma/models/user.prisma

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

Para más detalles, consulta la guía oficial de modelado de datos con Prisma.

Generando el Cliente de Base de Datos

El generador configura automáticamente el objetivo generate para crear un cliente TypeScript de Prisma con tipos seguros cada vez que construyes el proyecto. El cliente se escribe en generated/prisma (agregado a .gitignore).

También puedes generar manualmente el cliente en cualquier momento:

pnpm

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

yarn

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

npm

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

bun

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

Usa el objetivo prisma para ejecutar comandos de Prisma CLI desde la raíz del 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

El envoltorio en tiempo de ejecución en src/prisma.ts exporta:

• getPrisma() - carga la configuración de conexión de base de datos desde AWS AppConfig y crea un cliente Prisma usando autenticación IAM

El cliente automáticamente:

• Recupera la configuración de base de datos desde AWS AppConfig usando la variable de entorno RUNTIME_CONFIG_APP_ID
• Genera tokens de autenticación temporales a través de AWS RDS Signer para autenticación IAM
• Gestiona conexiones SSL/TLS con validación de certificados
• Maneja el pooling de conexiones a través de pools de conexión de base de datos persistentes

Creando Migraciones

Después de agregar o actualizar modelos bajo prisma/models/, usa migrate dev para generar archivos de migración y aplicarlos a tu base de datos local al mismo tiempo.

El objetivo prisma generado automáticamente inicia un contenedor de base de datos local antes de ejecutar:

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

Si solo deseas generar los archivos de migración sin aplicarlos a la base de datos local, agrega --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

Esto genera una nueva carpeta de migración en prisma/migrations cada vez que tu esquema cambia:

• Directorioprisma

  • Directoriomigrations

    • Directorio20260405013911_initial_migrations

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

Cuando despliegas el stack de AWS, la infraestructura generada aplica automáticamente las migraciones generadas a la base de datos desplegada.

Aplicando Migraciones Existentes

Cuando obtienes archivos de migración creados por otros desarrolladores, usa migrate deploy para aplicar esas migraciones existentes a tu base de datos 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

En este flujo de desarrollo local, migrate deploy aplica los archivos de migración a tu base de datos local; no despliega la base de datos en AWS.

Ejecutando Comandos de Prisma

El objetivo prisma generado expone la CLI de Prisma, por lo que puedes usarlo para ejecutar cualquier comando soportado por Prisma contra la base de datos local. Consulta la referencia de CLI de Prisma para los comandos disponibles.

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 Prisma Studio

Prisma Studio es un editor visual para tu base de datos local. Úsalo para explorar tablas, inspeccionar y editar registros, filtrar datos, seguir relaciones y ejecutar SQL sin procesar a través de la consola SQL integrada. Es útil para verificar migraciones y sembrar datos de prueba durante el desarrollo. Inícialo con:

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

Detener la Base de Datos Local

Detener dev (p. ej. con Ctrl+C) elimina automáticamente el contenedor de base de datos local, pero preserva el volumen nombrado para que tus datos persistan entre reinicios.

Windows

Debido a las limitaciones del manejo de señales en Windows, el contenedor no se elimina automáticamente cuando se detiene dev. Deberás eliminarlo manualmente:

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

Reemplaza <engine> con tu motor de contenedores (docker o finch), <scope> con el scope de tu workspace Nx (p. ej. proj), y <db-name> con el nombre de tu proyecto de base de datos (p. ej. my-db).

Conectando a la Base de Datos

En cualquier proyecto TypeScript, importa getPrisma desde tu paquete de base de datos y llámalo para obtener un cliente Prisma con tipos seguros:

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

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

getPrisma() devuelve un cliente inicializado de forma perezosa y en caché. Las llamadas subsiguientes dentro del mismo contexto de ejecución Lambda reutilizan el pool de conexiones existente en lugar de abrir uno nuevo.

El cliente Prisma expone modelos completamente tipados derivados de tu esquema prisma/models/, brindándote seguridad de tipos de extremo a extremo desde la base de datos hasta la respuesta de tu API.

Desplegando tu Base de Datos

El generador de base de datos relacional crea infraestructura CDK o Terraform basada en tu iacProvider seleccionado.

CDK

El constructo CDK se crea en common/constructs. Ejemplo 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,
      }
    });
  }
}

Esto aprovisiona un clúster Aurora con RDS Proxy, credenciales de administrador, usuario de base de datos de aplicación, registro de configuración en tiempo de ejecución y manejador de migraciones.

La infraestructura generada crea dos usuarios de base de datos:

• Usuario administrador - Creado durante el aprovisionamiento del clúster con credenciales almacenadas en AWS Secrets Manager
• Usuario de aplicación - Creado a través de un recurso personalizado Lambda con autenticación IAM habilitada y privilegios DML (SELECT, INSERT, UPDATE, DELETE) en la base de datos de aplicación

Terraform

El módulo Terraform se crea en common/terraform. Ejemplo 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
}

Esto aprovisiona un clúster Aurora con RDS Proxy, credenciales de administrador, Lambda create-db-user, registro de configuración en tiempo de ejecución, Lambda de migración y recursos de registro de contenedores.

La infraestructura generada crea dos usuarios de base de datos:

• Usuario administrador - Creado durante el aprovisionamiento del clúster con credenciales almacenadas en AWS Secrets Manager
• Usuario de aplicación - Creado a través de una función Lambda con autenticación IAM habilitada y privilegios DML (SELECT, INSERT, UPDATE, DELETE) en la base de datos de aplicación

El usuario de aplicación se crea automáticamente con un nombre aleatorio y autenticación IAM. El cliente de base de datos generado ya está configurado para autenticarse como este usuario usando tokens RDS de corta duración, por lo que tu código de aplicación nunca maneja contraseñas de base de datos.

Tu VPC debe incluir subredes públicas, subredes privadas con salida y subredes privadas aisladas. La base de datos puede ejecutarse en subredes privadas aisladas, mientras que las funciones Lambda de aplicación deben ejecutarse en subredes privadas con salida para que puedan alcanzar servicios de 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
}

Usa el generador connection para conectar un proyecto a esta base de datos — consulta la guía de conexión para el tipo de cómputo relevante (por ejemplo, FastAPI, servidor MCP, agente) para el cableado de infraestructura requerido para alcanzarla.

Escaneo de Imágenes

La imagen Docker construida para este proyecto se escanea en busca de vulnerabilidades como parte de la construcción usando Trivy, ejecutándose desde la imagen Trivy alojada en ECR.

Se agrega un target trivy a tu proyecto que escanea la imagen construida y falla la construcción si se encuentra alguna vulnerabilidad de severidad HIGH o CRITICAL. El Dockerfile generado utiliza una imagen base sin vulnerabilidades corregibles conocidas de estas severidades al momento de la generación, y actualiza las herramientas incluidas (como npm) para mantenerlo así.

El escaneo utiliza el mismo motor de contenedores que tu construcción de imagen (docker o finch), por lo que no se requieren herramientas adicionales. Dado que el escaneo solo se vuelve a ejecutar cuando la imagen cambia, una imagen sin cambios no se vuelve a escanear.

Las vulnerabilidades no corregibles se ignoran

El escaneo se ejecuta con --ignore-unfixed, por lo que las vulnerabilidades sin una corrección disponible no fallan la construcción, ya que no pueden ser accionadas actualizando herramientas en tu Dockerfile — no se reportan en la salida del escaneo de la construcción. A medida que se divulgan nuevas vulnerabilidades, el resultado de los escaneos puede cambiar con el tiempo, así que revisa la imagen periódicamente ejecutando trivy image <your-image> sin la bandera, y reconstruye contra una imagen base más reciente (o agrega pasos de contenedor para aplicar parches disponibles) una vez que se publique una corrección.

Supresión de Hallazgos de Trivy

Puede haber casos en los que desees suprimir una vulnerabilidad específica, por ejemplo, cuando aún no hay una corrección disponible y has evaluado el riesgo como aceptable.

Agrega el ID de vulnerabilidad (uno por línea) al archivo .trivyignore en la raíz de tu proyecto (es decir, junto a tu project.json):

.trivyignore

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

Para más detalles sobre el filtrado de hallazgos, consulta la documentación de filtrado de Trivy.

Configuración de RDS Proxy

La infraestructura generada incluye un RDS Proxy de forma predeterminada, que se sitúa entre tu aplicación y el clúster Aurora. RDS Proxy proporciona varios beneficios:

• Agrupación de conexiones - Mantiene un pool de conexiones de base de datos que pueden compartirse entre instancias de aplicación, reduciendo la sobrecarga de establecer nuevas conexiones
• Resiliencia de conexión - Maneja automáticamente las conmutaciones por error y reconexiones durante reemplazos de instancias Aurora o mantenimiento
• Autenticación IAM - Admite autenticación de base de datos basada en IAM, eliminando la necesidad de gestionar credenciales de base de datos en el código de tu aplicación
• Seguridad mejorada - Aplica cifrado TLS para todas las conexiones

Costo Adicional

RDS Proxy está habilitado de forma predeterminada pero incurre en cargos adicionales además del costo del clúster Aurora. Consulta precios de AWS RDS Proxy para más detalles. Si prefieres deshabilitar el proxy, consulta la sección a continuación.

Deshabilitar RDS Proxy

Puedes deshabilitar el proxy RDS de la siguiente manera:

CDK

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

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

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

Cuando RDS Proxy está deshabilitado, tu aplicación se conecta directamente al endpoint del clúster Aurora.

Terraform

De forma predeterminada, RDS Proxy está habilitado. Puedes deshabilitarlo si es necesario:

packages/infra/src/main.tf

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

Cuando RDS Proxy está deshabilitado, tu aplicación se conecta directamente al endpoint del clúster Aurora.

Requisitos SSL al Conectar sin RDS Proxy

Cuando te conectas directamente al clúster Aurora (sin RDS Proxy), el runtime que llama a getPrisma() debe confiar en el paquete CA de Amazon RDS. El cliente Prisma generado habilita la verificación de certificados; cómo hacer que el paquete CA esté disponible depende del runtime que se conecta a la base de datos.

Para Amazon RDS, usa el paquete CA global desde:

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

Imágenes de Contenedor del Runtime

Si preparas tu propia imagen de contenedor para el runtime, descarga el paquete CA de RDS en tu Dockerfile y agrégalo al almacén de confianza del sistema operativo.

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

Funciones Lambda Comprimidas

Para funciones Lambda comprimidas usando runtimes de Node.js 20 o posterior, carga el paquete CA de Amazon RDS configurando 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 más detalles, consulta los requisitos SSL/TLS para conexiones de Amazon RDS de AWS Lambda. Cuando uses RDS Proxy, no necesitas configurar el paquete CA de RDS en el runtime que se conecta a la base de datos.

Instancias del Clúster

Configure las instancias de escritura y lectura para su clúster 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
}

Capacidad Serverless

Controla los límites de escalado de Aurora Serverless v2 para adaptarse a tu carga de trabajo.

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
}

Versión del Motor

Fija una versión específica del motor Aurora.

Por defecto, la imagen del contenedor de base de datos local generada coincide con la versión predeterminada del motor Aurora. Si cambias la versión del motor Aurora, se recomienda también usar una versión de imagen de contenedor local que coincida para máxima compatibilidad. Consulta las notas de lanzamiento de AWS para versiones de Aurora PostgreSQL y versiones de Aurora MySQL para identificar la versión correspondiente de la base de datos comunitaria.

La imagen de la base de datos local se configura en el campo localDev.image del archivo config.json generado en la raíz de tu proyecto de base de datos. Actualiza ese valor cuando cambies las versiones del 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"
}

Protección contra Eliminación

La protección contra eliminación está habilitada por defecto (deletionProtection: true en CDK, deletion_protection = true en Terraform) para proteger el clúster de Aurora de eliminaciones accidentales.

Deshabilitar la Protección contra Eliminación

Puede deshabilitar la protección contra eliminación para entornos donde se espera la eliminación de la base de datos, como stacks de desarrollo o preview de corta duración.

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 Eliminación

El constructo CDK retiene el clúster Aurora por defecto (removalPolicy: RemovalPolicy.RETAIN). Cambia esto cuando quieras que la eliminación del stack CDK haga una instantánea o destruya el clúster en su lugar.

Cuando uses RemovalPolicy.DESTROY, la protección contra eliminación también debe estar deshabilitada antes de que el clúster pueda ser eliminado.

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 un entorno efímero donde la base de datos debe ser eliminada con el 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

Terraform no utiliza políticas de eliminación de CDK. Por defecto, el módulo crea una instantánea final al eliminar (skip_final_snapshot = false). Para omitir la instantánea final en un entorno 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
}

Pérdida de Datos

skip_final_snapshot = true borrará permanentemente todos los datos cuando se elimine el clúster. Úsalo solo en entornos efímeros (como pruebas automatizadas). Mantén skip_final_snapshot = false para todos los stacks persistentes y de producción para prevenir la pérdida de datos.

Registro y Monitoreo

Performance Insights está habilitado en la instancia de escritura de Aurora de forma predeterminada (cifrado con la clave KMS del clúster). También puede exportar los registros del motor de Aurora a CloudWatch Logs (postgresql para Aurora PostgreSQL; audit, error, general y slowquery para Aurora MySQL). Habilite la exportación de registros por base de datos:

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
}

Rotación de Clave de Cifrado

La clave KMS utilizada para cifrar el clúster Aurora y su secreto de credenciales tiene la rotación automática de claves habilitada por defecto. Deshabilítela si su política de seguridad gestiona la rotación 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
}

Limitaciones

engine = mysql

MySQL: Modo de Streaming de API Gateway

Al usar Aurora MySQL con respuestas de streaming de API Gateway (por ejemplo, con httpBatchStreamLink de tRPC), el cliente MySQL de Prisma retiene el bucle de eventos de Node.js después de que se completa una consulta, evitando que Lambda vacíe el stream y finalice la solicitud.

Para solucionar esto, desconecta explícitamente el cliente en un bloque finally después de cada consulta para que el bucle de eventos esté libre para salir y la respuesta de streaming pueda completarse.

Opción 1: por procedimiento

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

Opción 2: middleware de tRPC

Si estás usando el patrón de middleware, agrega la llamada $disconnect() al middleware para que todos los procedimientos construidos sobre él estén cubiertos automáticamente:

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

Esto no es necesario para PostgreSQL. El adaptador de PostgreSQL usa un pool de conexiones pg configurado con allowExitOnIdle: true, que permite que el bucle de eventos salga naturalmente sin una desconexión explícita. Debido a esta limitación, getPrisma() para MySQL no almacena en caché el cliente ni reutiliza conexiones entre invocaciones Lambda calientes. Se abre una nueva conexión en cada llamada, a diferencia del adaptador de PostgreSQL que almacena en caché el cliente a nivel de módulo y reutiliza el mismo pool de conexiones.

MySQL: Expiración de Token IAM

Los tokens de autenticación IAM de RDS expiran después de 15 minutos. El cliente Prisma de MySQL captura el token IAM como un valor estático en el momento en que se llama a getPrisma(). Una conexión abierta existente no se ve afectada, pero si se necesita establecer una nueva conexión después de que el token haya expirado, la autenticación fallará. El adaptador de PostgreSQL evita esto refrescando el token dinámicamente cada vez que el pool abre una nueva conexión, pero el adaptador de MySQL no tiene un mecanismo equivalente.

Precaución

Ten cuidado con tareas que se ejecutan durante más de 15 minutos. Si el cliente MySQL necesita abrir una nueva conexión después de que el token IAM original haya expirado, la autenticación fallará.

Para tareas de larga duración como trabajos por lotes o migraciones de datos, llama a getPrisma() al inicio de cada unidad de trabajo en lugar de una vez para toda la operación. Debido a que getPrisma() siempre crea un cliente nuevo y obtiene un nuevo token IAM para MySQL, esto asegura que cada conexión se autentique con un token válido.

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu workspace. Las siguientes conexiones involucran este proyecto:

API tRPC a Base de Datos RelacionalConecta una API tRPC a una base de datos relacional Aurora

API Smithy a Base de Datos RelacionalConecta una API Smithy a una base de datos relacional Aurora

TypeScript Agent a Base de Datos RelacionalConecta un TypeScript Agent a una base de datos relacional Aurora

Servidor MCP a Base de Datos RelacionalConecta un Servidor MCP en TypeScript a una base de datos relacional Aurora