Ch2. 토폴로지와 환경 구성

권장 토폴로지

• 온라인 트래픽은 연결 풀 계층을 통해 접속
• 마이그레이션은 DIRECT_DATABASE_URL로 직접 접속
• 읽기 부하는 리드 레플리카로 분산(ORM 레벨 또는 리포팅 파이프라인)

Node 런타임에서 PrismaClient 수명 관리

// src/lib/prisma.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma?: PrismaClient
}

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ['warn', 'error'],
  })

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma
}

핫리로드 환경에서는 싱글턴으로 관리해 연결 폭증을 방지합니다. 프로덕션에서는 프로세스 수 대비 최대 연결 수를 사전 계산해야 합니다.

연결 수 산정 기본식

총 연결 수 = (API 인스턴스 수 x 인스턴스당 Prisma 풀 상한) + 배치/워커 연결 + 운영 도구 연결

DB 최대 연결의 70~80%를 초과하지 않도록 상한을 잡고, 나머지는 관리/장애 대응 여유로 남깁니다.

쿼리 캐싱 레이어 (v7.4.0+)

Prisma ORM v7.4.0부터 내장 LRU 쿼리 캐싱이 도입되었습니다. 동일한 쿼리 형태가 반복되면 SQL 재컴파일을 건너뛰어 이벤트 루프 경합을 줄입니다.

• 별도 설정 없이 자동 적용 (opt-out 방식)
• Prisma Postgres의 cacheStrategy(TTL/SWR)와는 별개 — ORM 레벨 컴파일 캐시
• v7.3.0의 compilerBuild: "fast" | "small" 옵션과 함께 사용하면 컴파일러 성능 추가 조정 가능

서버리스/짧은 수명 워크로드 주의점

• 콜드 스타트가 많으면 연결 생성/해제 비용이 급증
• 풀링 계층 없이 직접 연결 시 DB 연결 한계에 빠르게 도달
• 장시간 트랜잭션 로직은 서버리스 함수에서 분리

Prisma 스키마/환경 변수 운영 팁

# 앱 런타임
DATABASE_URL="postgresql://app_prod:***@pgbouncer:6432/service"

# 마이그레이션/관리 작업
DIRECT_DATABASE_URL="postgresql://migrate_prod:***@primary:5432/service"

prisma migrate deploy는 반드시 DIRECT_DATABASE_URL이 유효한 환경에서만 실행합니다.

배포 전 점검 항목

• 인스턴스 스케일 아웃 시 DB 연결 상한 재계산
• PgBouncer/Proxy 장애 시 우회 경로 문서화
• 리드 레플리카 지연 알림 임계치 설정
• 마이그레이션 전용 경로가 런타임 경로와 분리됨