콘텐츠로 이동
@aws/nx-plugin
Blog

TypeScript 관계형 데이터베이스

이 생성기는 Amazon Aurora (PostgreSQL 또는 MySQL)와 Prisma ORM을 기반으로 하는 새로운 관계형 데이터베이스 프로젝트를 생성합니다. AWS CDK 또는 Terraform을 사용하여 데이터베이스를 프로비저닝하고 관리하는 데 필요한 애플리케이션 코드와 인프라를 생성하며, 선언적 스키마 정의, 자동 마이그레이션 배포 및 타입 안전 ORM 클라이언트를 제공합니다.

사용법

섹션 제목: “사용법”

관계형 데이터베이스 생성

섹션 제목: “관계형 데이터베이스 생성”

두 가지 방법으로 새로운 관계형 데이터베이스 프로젝트를 생성할 수 있습니다:

이 제너레이터 실행@aws/nx-plugin:ts#rdb

pnpm nx g @aws/nx-plugin:ts#rdb
명령 구성하기10

필수

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

옵션

섹션 제목: “옵션”
제너레이터 옵션10 옵션
name필수string

생성할 데이터베이스 프로젝트의 이름

directorystring기본값: packages

애플리케이션을 저장할 디렉토리

infraenum기본값: aurora

프로비저닝할 관계형 데이터베이스 서비스입니다.

auroranone
engineenum기본값: postgres

선택한 서비스와 함께 사용할 데이터베이스 엔진

postgresmysql
frameworkenum기본값: prisma

생성된 프로젝트에 사용할 ORM 프레임워크입니다.

prisma
iacenum기본값: inherit

선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.

inheritcdkterraform
subDirectorystring

프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.

databaseUserstring기본값: dbadmin

데이터베이스 관리자 사용자 이름입니다. 기본값은 'dbadmin'입니다.

databaseNamestring

초기 데이터베이스 이름입니다. 기본값은 프로젝트 이름입니다.

preferInstallDependenciesboolean기본값: true

생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요(후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번만 설치하세요.

생성기 출력

섹션 제목: “생성기 출력”

생성기는 <directory>/<name> 디렉토리에 다음과 같은 프로젝트 구조를 생성합니다:

  • 디렉터리prisma
    • 디렉터리models
      • example.prisma Example model definition
    • schema.prisma Main Prisma schema (references models)
  • 디렉터리src
    • 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
  • .trivyignore Vulnerability IDs to suppress when scanning the migration image
  • 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
  • README.md Project readme
  • rolldown.config.ts Bundler configuration invoked by the bundle target
  • tsconfig.json TypeScript project references
  • tsconfig.lib.json TypeScript configuration for the library build
  • tsconfig.spec.json TypeScript configuration for tests
  • vitest.config.mts Vitest configuration

로컬 개발 스크립트는 모든 데이터베이스 프로젝트에서 공유되며 packages/common/scripts/에 생성됩니다:

  • 디렉터리packages/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)

인프라

섹션 제목: “인프라”

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

  • 디렉터리packages/common/constructs
    • 디렉터리src
      • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
        • …
      • 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
        • …
      • index.ts app에서 constructs를 내보내는 진입점
    • project.json 프로젝트 빌드 타겟 및 구성
  • 디렉터리packages/common/constructs/src
    • 디렉터리app
      • 디렉터리dbs
        • <name>.ts 데이터베이스에 특정한 인프라
    • 디렉터리core
      • 디렉터리rdb
        • aurora.ts 범용 Aurora 데이터베이스 구성

아키텍처

섹션 제목: “아키텍처”

배포된 데이터베이스는 다음과 같은 아키텍처를 가집니다. 기본적으로 Amazon RDS Proxy가 Aurora 클러스터 앞에 위치하여 연결을 풀링하고 IAM 인증을 활성화합니다 — 대안은 RDS Proxy 비활성화를 참조하세요. PostgreSQL 또는 MySQL 엔진을 선택하든 아키텍처는 동일하며, Aurora 엔진 유형만 다릅니다.

Loading the diagram…

로컬 개발

섹션 제목: “로컬 개발”

데이터 모델링

섹션 제목: “데이터 모델링”

생성된 프로젝트는 Prisma ORM을 사용하여 데이터베이스 스키마를 정의하고 타입 안전 클라이언트를 생성합니다. 워크플로는 모델 우선 방식입니다: 데이터베이스 프로젝트의 prisma/models/ 디렉토리에 Prisma 모델 파일을 추가하거나 업데이트한 다음, 해당 모델 변경 사항으로부터 마이그레이션을 생성합니다.

User 모델 예시:

packages/postgres/prisma/models/user.prisma
model User {
  id          Int      @id @default(autoincrement())
  firstName   String
  lastName    String
}

자세한 내용은 공식 Prisma 데이터 모델링 가이드를 참조하세요.

데이터베이스 클라이언트 생성

섹션 제목: “데이터베이스 클라이언트 생성”

생성기는 프로젝트를 빌드할 때마다 타입 안전 TypeScript Prisma 클라이언트를 생성하도록 generate 타겟을 자동으로 구성합니다. 클라이언트는 generated/prisma에 작성됩니다(.gitignore에 추가됨).

언제든지 수동으로 클라이언트를 생성할 수도 있습니다:

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

워크스페이스 루트에서 Prisma CLI 명령을 실행하려면 prisma 타겟을 사용하세요:

Terminal window
pnpm nx run <project>:prisma generate

src/prisma.ts의 런타임 래퍼는 다음을 내보냅니다:

  • getPrisma() - AWS AppConfig에서 데이터베이스 연결 설정을 로드하고 IAM 인증을 사용하여 Prisma 클라이언트를 생성합니다

클라이언트는 자동으로:

  • RUNTIME_CONFIG_APP_ID 환경 변수를 사용하여 AWS AppConfig에서 데이터베이스 구성을 검색합니다
  • IAM 인증을 위해 AWS RDS Signer를 통해 임시 인증 토큰을 생성합니다
  • 인증서 검증을 통한 SSL/TLS 연결을 관리합니다
  • 영구 데이터베이스 연결 풀을 통해 연결 풀링을 처리합니다

마이그레이션 생성

섹션 제목: “마이그레이션 생성”

prisma/models/ 아래에 모델을 추가하거나 업데이트한 후, migrate dev를 사용하여 마이그레이션 파일을 생성하고 동시에 로컬 데이터베이스에 적용합니다.

생성된 prisma 타겟은 실행 전에 자동으로 로컬 데이터베이스 컨테이너를 시작합니다:

Terminal window
pnpm nx run <project>:prisma migrate dev

로컬 데이터베이스에 적용하지 않고 마이그레이션 파일만 생성하려면 --create-only를 추가하세요:

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

이렇게 하면 스키마가 변경될 때마다 prisma/migrations에 새로운 마이그레이션 폴더가 생성됩니다:

  • 디렉터리prisma
    • 디렉터리migrations
      • 디렉터리20260405013911_initial_migrations
        • migration.sql
      • migration_lock.toml
    • schema.prisma

AWS 스택을 배포하면 생성된 인프라가 자동으로 생성된 마이그레이션을 배포된 데이터베이스에 적용합니다.

기존 마이그레이션 적용

섹션 제목: “기존 마이그레이션 적용”

다른 개발자가 생성한 마이그레이션 파일을 가져온 경우, migrate deploy를 사용하여 해당 기존 마이그레이션을 로컬 데이터베이스에 적용합니다.

Terminal window
pnpm nx run <project>:prisma migrate deploy

이 로컬 개발 플로우에서 migrate deploy는 마이그레이션 파일을 로컬 데이터베이스에 적용합니다. AWS에 데이터베이스를 배포하지는 않습니다.

Prisma 명령 실행

섹션 제목: “Prisma 명령 실행”

생성된 prisma 타겟은 Prisma CLI를 노출하므로 로컬 데이터베이스에 대해 Prisma가 지원하는 모든 명령을 실행할 수 있습니다. 사용 가능한 명령은 Prisma CLI 참조를 참조하세요.

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

Prisma Studio 사용

섹션 제목: “Prisma Studio 사용”

Prisma Studio는 로컬 데이터베이스를 위한 시각적 편집기입니다. 테이블 탐색, 레코드 검사 및 편집, 데이터 필터링, 관계 추적, 내장 SQL 콘솔을 통한 원시 SQL 실행에 사용할 수 있습니다. 개발 중 마이그레이션 검증 및 테스트 데이터 시딩에 유용합니다. 다음 명령으로 실행하세요:

Terminal window
pnpm nx run <project>:prisma studio

로컬 데이터베이스 중지

섹션 제목: “로컬 데이터베이스 중지”

dev를 중지하면(예: Ctrl+C로) 로컬 데이터베이스 컨테이너가 자동으로 제거되지만, 명명된 볼륨은 보존되어 재시작 시에도 데이터가 유지됩니다.

데이터베이스 연결

섹션 제목: “데이터베이스 연결”

모든 TypeScript 프로젝트에서 데이터베이스 패키지에서 getPrisma를 가져와 호출하여 타입 안전 Prisma 클라이언트를 얻을 수 있습니다:

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


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

getPrisma()는 지연 초기화되고 캐시된 클라이언트를 반환합니다. 동일한 Lambda 실행 컨텍스트 내에서 후속 호출은 새 연결을 열지 않고 기존 연결 풀을 재사용합니다.

Prisma 클라이언트는 prisma/models/ 스키마에서 파생된 완전히 타입이 지정된 모델을 노출하여 데이터베이스에서 API 응답까지 엔드투엔드 타입 안전성을 제공합니다.

getPrisma()는 런타임에 AWS AppConfig에서 데이터베이스 연결 설정을 가져옵니다.

데이터베이스 배포

섹션 제목: “데이터베이스 배포”

관계형 데이터베이스 생성기는 선택한 iac에 따라 CDK 또는 Terraform 인프라를 생성합니다.

CDK 구성은 common/constructs에 생성됩니다. 사용 예시:

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

이는 RDS Proxy, 관리자 자격 증명, 애플리케이션 데이터베이스 사용자, 런타임 구성 등록 및 마이그레이션 핸들러가 포함된 Aurora 클러스터를 프로비저닝합니다.

생성된 인프라는 두 개의 데이터베이스 사용자를 생성합니다:

  • 관리자 사용자 - 클러스터 프로비저닝 중에 생성되며 자격 증명은 AWS Secrets Manager에 저장됩니다
  • 애플리케이션 사용자 - Lambda 사용자 지정 리소스를 통해 생성되며 IAM 인증이 활성화되고 애플리케이션 데이터베이스에 대한 DML 권한(SELECT, INSERT, UPDATE, DELETE)을 가집니다

애플리케이션 사용자는 무작위 이름으로 자동 생성되며 IAM 인증이 활성화됩니다. 생성된 데이터베이스 클라이언트는 이미 단기 RDS 토큰을 사용하여 이 사용자로 인증하도록 구성되어 있으므로, 애플리케이션 코드는 데이터베이스 비밀번호를 처리할 필요가 없습니다.

VPC에는 퍼블릭 서브넷, 이그레스가 있는 프라이빗 서브넷, 프라이빗 격리 서브넷이 포함되어야 합니다. 데이터베이스는 프라이빗 격리 서브넷에서 실행할 수 있으며, 애플리케이션 Lambda 함수는 AppConfig와 같은 AWS 서비스에 도달할 수 있도록 이그레스가 있는 프라이빗 서브넷에서 실행해야 합니다.

VPC 구성 예시를 보려면 여기를 클릭하세요.

connection 생성기를 사용하여 프로젝트를 이 데이터베이스에 연결하세요 — 데이터베이스에 도달하는 데 필요한 인프라 연결에 대해서는 관련 컴퓨팅 유형(예: FastAPI, MCP 서버, 에이전트)에 대한 연결 가이드를 참조하세요.

이미지 스캔

섹션 제목: “이미지 스캔”

이 프로젝트를 위해 빌드된 Docker 이미지는 ECR 호스팅 Trivy 이미지에서 실행되는 Trivy를 사용하여 취약점을 스캔할 수 있습니다.

trivy 타겟이 프로젝트에 추가되어 빌드된 이미지를 스캔하고 HIGH 또는 CRITICAL 심각도의 취약점이 발견되면 0이 아닌 값으로 종료합니다. 생성된 Dockerfile은 생성 시점에 이러한 심각도의 알려진 수정 가능한 취약점이 없는 베이스 이미지를 사용하며, 번들된 도구(예: npm)를 업그레이드하여 이를 유지합니다.

스캔은 이미지 빌드와 동일한 컨테이너 엔진(docker 또는 finch)을 사용하므로 추가 도구가 필요하지 않습니다. 스캔은 캐시되지 않습니다. 읽는 이미지가 디스크가 아닌 컨테이너 엔진에 있기 때문입니다. 따라서 항상 실제 이미지를 스캔하며, 더 이상 존재하지 않는 이미지에 대해 캐시된 통과를 보고하는 대신 명확하게 실패합니다. 따라서 각 실행은 이미지당 수십 초가 걸리며 Trivy의 취약점 데이터베이스를 새로 고치므로 네트워크 액세스가 필요합니다. 제공되는 trivy 루트 스크립트는 워크스페이스의 모든 이미지를 스캔합니다:

Terminal window
pnpm trivy

Trivy 결과 억제

섹션 제목: “Trivy 결과 억제”

특정 취약점을 억제하고 싶은 경우가 있을 수 있습니다. 예를 들어 아직 수정 사항이 없고 위험을 허용 가능한 것으로 평가한 경우입니다.

프로젝트 루트의 .trivyignore 파일(즉, project.json 옆)에 취약점 ID를 한 줄에 하나씩 추가하세요:

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

결과 필터링에 대한 자세한 내용은 Trivy 필터링 문서를 참조하세요.

RDS Proxy 구성

섹션 제목: “RDS Proxy 구성”

생성된 인프라에는 기본적으로 RDS Proxy가 포함되어 있으며, 이는 애플리케이션과 Aurora 클러스터 사이에 위치합니다. RDS Proxy는 여러 가지 이점을 제공합니다:

  • 연결 풀링 - 애플리케이션 인스턴스 간에 공유할 수 있는 데이터베이스 연결 풀을 유지하여 새 연결 설정의 오버헤드를 줄입니다
  • 연결 복원력 - Aurora 인스턴스 교체 또는 유지 관리 중 장애 조치 및 재연결을 자동으로 처리합니다
  • IAM 인증 - IAM 기반 데이터베이스 인증을 지원하여 애플리케이션 코드에서 데이터베이스 자격 증명을 관리할 필요가 없습니다
  • 향상된 보안 - 모든 연결에 대해 TLS 암호화를 강제합니다

RDS Proxy 비활성화

섹션 제목: “RDS Proxy 비활성화”

다음과 같이 RDS 프록시를 비활성화할 수 있습니다:

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

RDS Proxy가 비활성화되면 애플리케이션이 Aurora 클러스터 엔드포인트에 직접 연결됩니다.

RDS Proxy 없이 연결할 때의 SSL 요구사항

섹션 제목: “RDS Proxy 없이 연결할 때의 SSL 요구사항”

Aurora 클러스터에 직접 연결할 때(RDS Proxy 없이), getPrisma()를 호출하는 런타임은 Amazon RDS CA 번들을 신뢰해야 합니다. 생성된 Prisma 클라이언트는 인증서 검증을 활성화합니다. CA 번들을 사용 가능하게 만드는 방법은 데이터베이스에 연결하는 런타임에 따라 다릅니다.

Amazon RDS의 경우 다음에서 글로벌 CA 번들을 사용하세요:

https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
런타임 컨테이너 이미지
섹션 제목: “런타임 컨테이너 이미지”

런타임을 위한 자체 컨테이너 이미지를 준비하는 경우, Dockerfile에서 RDS CA 번들을 다운로드하고 운영 체제 신뢰 저장소에 추가하세요.

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
압축된 Lambda 함수
섹션 제목: “압축된 Lambda 함수”

Node.js 20 이상 런타임을 사용하는 압축된 Lambda 함수의 경우, NODE_EXTRA_CA_CERTS를 설정하여 Amazon RDS CA 번들을 로드하세요:

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

자세한 내용은 AWS Lambda Amazon RDS 연결을 위한 SSL/TLS 요구사항을 참조하세요. RDS Proxy를 사용하는 경우 데이터베이스에 연결하는 런타임에서 RDS CA 번들을 구성할 필요가 없습니다.

클러스터 인스턴스

섹션 제목: “클러스터 인스턴스”

Aurora 클러스터의 writer 및 reader 인스턴스를 구성합니다.

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

서버리스 용량

섹션 제목: “서버리스 용량”

워크로드에 맞게 Aurora Serverless v2 스케일링 제한을 제어합니다. 두 프로바이더 모두 기본적으로 최소 0.5 ACU, 최대 4로 설정됩니다.

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


const db = new MyDatabase(this, 'Db', {
  ...
  serverlessV2MinCapacity: 0.5,
  serverlessV2MaxCapacity: 8,
});

엔진 버전

섹션 제목: “엔진 버전”

특정 Aurora 엔진 버전을 고정합니다.

기본적으로 생성된 로컬 데이터베이스 컨테이너 이미지는 기본 Aurora 엔진 버전과 일치합니다. Aurora 엔진 버전을 변경하는 경우, 최대 호환성을 위해 일치하는 로컬 컨테이너 이미지 버전도 사용하는 것이 좋습니다. 해당하는 커뮤니티 데이터베이스 버전을 확인하려면 Aurora PostgreSQL 버전 및 Aurora MySQL 버전에 대한 AWS 릴리스 노트를 참조하세요.

로컬 데이터베이스 이미지는 데이터베이스 프로젝트 루트에 생성된 config.json 파일의 localDev.image 필드에 구성됩니다. 엔진 버전을 변경할 때 해당 값을 업데이트하세요.

engine = postgres
packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraPostgresEngineVersion.VER_17_7,
});
engine = mysql
packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraMysqlEngineVersion.VER_3_12_0,
});

삭제 보호

섹션 제목: “삭제 보호”

Aurora 클러스터는 두 개의 독립적인 보호 장치로 보호되므로, 둘 중 하나만 끄는 것으로는 데이터를 삭제할 수 없습니다:

  • deletionProtection, RDS에 의해 적용됩니다.
  • RemovalPolicy.RETAIN, CloudFormation에 의해 적용되며, 스택에서 제거될 때 클러스터를 그대로 유지합니다.

데이터베이스 삭제

섹션 제목: “데이터베이스 삭제”

단기 개발 또는 프리뷰 스택과 같이 데이터베이스 삭제가 예상되는 환경에서는 보호를 비활성화할 수 있습니다.

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

제거 정책

섹션 제목: “제거 정책”

CDK 구성 요소는 기본적으로 Aurora 클러스터를 유지합니다(removalPolicy: RemovalPolicy.RETAIN). CDK 스택 삭제 시 클러스터를 스냅샷하거나 삭제하려면 이 설정을 변경하세요.

RemovalPolicy.DESTROY를 사용할 때는 클러스터를 삭제하기 전에 삭제 보호도 비활성화해야 합니다.

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

데이터베이스가 스택과 함께 삭제되어야 하는 임시 환경의 경우:

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

로깅 및 모니터링

섹션 제목: “로깅 및 모니터링”
engine = postgres

postgresql 로그는 Aurora PostgreSQL에 대해 내보내지며, 로깅은 DDL 문으로만 범위가 지정됩니다(log_statement=ddl). 따라서 각 문이 개별적으로 전송되는 한 문 매개변수 값은 절대 로깅되지 않습니다. log_statement=ddl은 다중 문 배치(예: 단일 psql -c "a;b;c" 호출)의 전체 원시 텍스트를 그대로 로깅하며, 배치 내 어떤 문이라도 DDL인 경우 동일한 배치의 모든 DML 값을 포함합니다.

engine = mysql

Aurora MySQL에 대해 audit 및 error 로그가 내보내집니다 — general 및 slowquery는 DML 값을 포함한 전체 문장 텍스트를 로깅하므로 의도적으로 제외됩니다. Advanced Auditing은 연결 및 DDL(server_audit_events=CONNECT,QUERY_DDL)로 범위가 지정되므로 문장 매개변수 값은 절대 로깅되지 않습니다.

Performance Insights는 기본적으로 Aurora 라이터 인스턴스에서 활성화됩니다(클러스터의 KMS 키로 암호화됨). Aurora 엔진 로그도 기본적으로 CloudWatch Logs로 내보내지며, 행 데이터를 노출하지 않고 스키마 수준의 활동을 표시하도록 구성됩니다.

내보낸 로그 볼륨 — 따라서 CloudWatch Logs 수집 비용 — 은 전체 문장 텍스트를 포함하는 로그 유형이 제외되므로 쿼리 트래픽보다는 스키마 변경 및 연결에 따라 확장됩니다. Aurora MySQL에서는 CONNECT 감사 이벤트가 연결당 발생하므로, 요청당 연결을 여는 워크로드는 풀링하는 워크로드보다 더 많은 로그를 생성합니다.

필요하지 않은 경우 데이터베이스별로 로그 내보내기를 비활성화하세요:

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

암호화 키 로테이션

섹션 제목: “암호화 키 로테이션”

Aurora 클러스터와 자격 증명 시크릿을 암호화하는 데 사용되는 KMS 키는 기본적으로 자동 키 로테이션이 활성화되어 있습니다. 보안 정책에서 로테이션을 외부에서 관리하는 경우 이를 비활성화하세요.

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

관리자 자격 증명

섹션 제목: “관리자 자격 증명”

Aurora 관리자(마스터) 사용자의 비밀번호는 RDS 관리형 마스터 사용자 비밀번호를 사용하여 Aurora 자체가 AWS Secrets Manager에서 생성하고 교체합니다. 인프라 코드는 비밀번호를 받지 않으므로 CloudFormation 템플릿이나 Terraform 상태 파일로 유출될 수 없습니다. Aurora는 배포하거나 유지 관리할 교체 함수 없이 7일마다 시크릿을 교체합니다.

시크릿은 클러스터와 동일한 고객 관리형 KMS 키로 암호화됩니다.

애플리케이션은 이러한 자격 증명을 사용하지 않습니다. IAM 인증을 사용하여 최소 권한 데이터베이스 사용자로 연결합니다. 마이그레이션 및 create-db-user 핸들러만 관리자 시크릿을 읽으며, 각각은 해당 시크릿과 KMS 키에만 액세스 권한이 부여됩니다.

관리자 시크릿은 기본 클러스터에서 secret.secretArn으로 노출되며, grantSecretRead는 소비자에게 읽기 액세스 권한을 부여합니다:

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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


db.grantSecretRead(myFunction);

제한사항

섹션 제목: “제한사항”
engine = mysql

MySQL: API Gateway 스트리밍 모드

섹션 제목: “MySQL: API Gateway 스트리밍 모드”

Aurora MySQL을 API Gateway 스트리밍 응답(예: tRPC의 httpBatchStreamLink)과 함께 사용할 때, Prisma MySQL 클라이언트는 쿼리가 완료된 후에도 Node.js 이벤트 루프를 유지하여 Lambda가 스트림을 플러시하고 요청을 종료하는 것을 방지합니다.

이 문제를 해결하려면 각 쿼리 후 finally 블록에서 클라이언트를 명시적으로 연결 해제하여 이벤트 루프가 종료되고 스트리밍 응답이 완료될 수 있도록 하세요.

옵션 1: 프로시저별

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

옵션 2: tRPC 미들웨어

미들웨어 패턴을 사용하는 경우, 미들웨어에 $disconnect() 호출을 추가하여 이를 기반으로 구축된 모든 프로시저가 자동으로 적용되도록 하세요:

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

MySQL: IAM 토큰 만료

섹션 제목: “MySQL: IAM 토큰 만료”

RDS IAM 인증 토큰은 15분 후에 만료됩니다. MySQL Prisma 클라이언트는 getPrisma()가 호출될 때 IAM 토큰을 정적 값으로 캡처합니다. 기존 열린 연결은 영향을 받지 않지만, 토큰이 만료된 후 새 연결을 설정해야 하는 경우 인증이 실패합니다. PostgreSQL 어댑터는 풀이 새 연결을 열 때마다 토큰을 동적으로 새로 고쳐 이를 방지하지만, MySQL 어댑터에는 동등한 메커니즘이 없습니다.

배치 작업이나 데이터 마이그레이션과 같은 장기 실행 작업의 경우, 전체 작업에 대해 한 번이 아니라 각 작업 단위의 시작 시 getPrisma()를 호출하세요. getPrisma()는 MySQL의 경우 항상 새로운 클라이언트를 생성하고 새로운 IAM 토큰을 가져오므로 각 연결이 유효한 토큰으로 인증되도록 보장합니다.

연결

섹션 제목: “연결”

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합하세요. 다음 연결은 이 프로젝트와 관련이 있습니다:

tRPCAmazon Aurora
tRPC API to Relational DatabasetRPC API를 Aurora 관계형 데이터베이스에 연결
SmithyAmazon Aurora
Smithy API to Relational DatabaseSmithy API를 Aurora 관계형 데이터베이스에 연결
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational DatabaseTypeScript Agent를 Aurora 관계형 데이터베이스에 연결
Model Context ProtocolAmazon Aurora
MCP Server to Relational DatabaseTypeScript MCP Server를 Aurora 관계형 데이터베이스에 연결