ADR-0004: Database: Neon Serverless PostgreSQL¶
Umbra 의 영속 데이터 저장소로 Neon Serverless PostgreSQL 을 채택한다.
Status¶
Accepted
- Decided at — 2026-04-13
- Decided by — Pablo
Context¶
Umbra 는 결제, 권한, 스냅샷, 감사 로그 등 일관성과 트랜잭션이 중요한 데이터를 저장해야 한다. 선택 기준은 다음과 같다.
- 강한 트랜잭션 보장 (결제 + 이벤트 Outbox 가 같은 트랜잭션)
- JSONB 지원 (Restore Point 스냅샷 저장)
- 관리형 서비스 (MVP 운영 부담 최소화)
- 한국 리전 지원
- PR 별 DB branching (마이그레이션 안전 검증)
후보: Neon, Supabase, AWS RDS, Google Cloud SQL, PlanetScale (MySQL).
Decision¶
Neon Serverless PostgreSQL 을 채택한다. MVP 는 Launch plan 으로 시작하며 트래픽 증가 시 Scale plan 전환.
선택 근거:
- PostgreSQL 네이티브 — JSONB, CTE, LATERAL JOIN, FOR UPDATE SKIP LOCKED 등 Umbra 가 의존하는 기능 풀 지원
- 서울 리전(ap-northeast-2) 제공 — 사용자 latency 최소화
- Branching — PR 마다 DB 브랜치 자동 생성으로 마이그레이션 검증 워크플로우 가능
- Pooler endpoint 내장 — PgBouncer 를 직접 운영하지 않아도 됨
- Serverless 과금 — 트래픽이 적은 MVP 초기에 비용 효율적
Consequences¶
Positive¶
- PR 별 DB 분리로 마이그레이션 드리프트 조기 감지 (Atlas 와 결합)
- Pooler 관리 부담 0
- 서울 리전으로 앱 서버(Fly.io nrt)와 ~50ms 내 latency
- Neon 자체 PITR 로 7일 백업 (Scale plan)
Negative¶
- PostgreSQL 기능 중 일부(extension)는 Neon 허용 목록에 의존
- 서버리스 아키텍처 특성상 콜드 스타트 (Launch plan 기준)
- 단일 공급자 종속 — 타 PostgreSQL 으로 이전 시 branching 기능 대체 필요
Neutral¶
- Temporal Server 의 persistence 를 Neon 에 같이 두어 비용 효율화 (별도 schema
temporal) - SQL 은 표준 PostgreSQL 이라 마이그레이션은 용이
Alternatives considered¶
Alternative 1: Supabase¶
Pros
- PostgreSQL + Auth + Realtime 통합
- 한국 개발자 친숙도 높음
Cons
- Auth 는 Discord OAuth2 로 자체 구현 예정이라 중복
- Branching 기능이 Neon 만큼 성숙하지 않음
- Realtime 은 불필요
Why rejected — Umbra 는 DB 만 필요하며, Neon 의 branching 이 결정적 이점.
Alternative 2: AWS RDS / Google Cloud SQL¶
Pros
- 엔터프라이즈급 안정성
- 다양한 tuning 옵션
Cons
- Managed 지만 운영 부담 있음 (VPC, security group, parameter group)
- Branching 기능 없음 (스냅샷 기반 복제만 가능)
- MVP 비용 부담
Why rejected — MVP 운영 부담 최소화 기준 미달. 프로덕션 트래픽 시 재평가 가능.
Alternative 3: PlanetScale (MySQL)¶
Pros
- Branching 기능 강력
- Vitess 기반 수평 확장
Cons
- MySQL 이라 JSONB, CTE 등 PostgreSQL 고유 기능 부재
- Foreign key 미지원 (PlanetScale 정책)
Why rejected — Umbra 는 JSONB(스냅샷)와 FK(도메인 간 참조)에 의존. MySQL 의 제약이 결정적.
Compliance¶
DATABASE_URL은 Pooler endpoint 를 사용 (-poolersuffix)- Direct endpoint 는 Temporal 같은 long-running 연결에만 사용
- Atlas 가 Neon 의 branch 를 dev env 로 활용
Revisit triggers¶
- 월간 비용이 Scale plan 상한을 초과하면 self-hosted PostgreSQL 재평가
- Neon 리전 장애가 반복되면 멀티 리전 또는 다른 공급자 검토
- 쓰기 TPS 가 Neon 단일 브랜치 한계에 근접하면 샤딩 설계