Skip to Content
DecisionsADR-0022: community-v2 Supabase 의 dev/prod 격리를 Supabase 영속 브랜치 + 하이브리드 마이그레이션으로 한다

ADR-0022: community-v2 Supabase 의 dev/prod 격리를 Supabase 영속 브랜치 + 하이브리드 마이그레이션으로 한다

  • Status: Accepted (Amended by ADR-0029)
  • Date: 2026-10-15
  • 관련: HMH-9973 (환경분리 계획) · HMH-9978 (이번 1단계) · 에픽 HMH-9765 · ADR-0021(채팅 첨부 R2)

정정(amended). 아래 Context 의 “이 프로젝트엔 … 리셉션 세션·세금챗(assessed_prices_unit·tax_chat_turn)·모더레이션도 함께 산다”는 프로젝트별 소유 서술은 더 이상 정확하지 않다: 리셉션은 etc 로 이전했고(ADR-0029), 세무 AI챗(assessed_prices_unit 등)은 애초에 community-v2 가 아니라 별도 tax-chat 프로젝트 소유였다. 현재 프로젝트별 소유는 Supabase 프로젝트 지도 를 보라. dev/prod 격리를 영속 브랜치 + 하이브리드 마이그레이션으로 한다는 이 ADR 의 결정 자체는 community-v2 에 대해 유효하다.

Context

community-v2 Supabase 는 dev/prod 공유 1프로젝트(ref rvbpczkrxvzlszpdxady)다. 한 DB·한 R2 버킷에 dev 테스트와 prod 실데이터가 섞인다. 통합 채팅(channel/channel_member/message)을 prod 로 켜기 전에 dev/prod 를 격리해야 한다. 이 프로젝트엔 채팅 외에 리셉션 세션(reception_session)·세금챗(assessed_prices_unit·tax_chat_turn)·모더레이션 감사도 함께 산다 — 즉 격리는 프로젝트 전체에 영향을 준다.

제약·그때의 사실:

  • 마이그레이션은 supabase/migrations/*.sql(번호 접두 0001~)을 psql 스크립트(supabase/scripts/apply-migrations.sh)로 적용한다. 자체 추적 테이블 public._supabase_sql_migrations 를 쓰고, 멱등(if not exists)이다. CI 는 .github/workflows/supabase-migrate.yml(main push → prod).
  • 레포에 Supabase CLI·config.toml·브랜칭 인프라가 없었다(sendbird-exit-plan.md 명시).
  • Supabase 브랜칭은 supabase/migrations/ 를 자체적으로 자동 적용한다(브랜치 생성 시 전량, GitHub 연동 시 push 마다 미적용분). 즉 브랜칭의 마이그레이션 러너와 우리 psql 러너가 이중화될 수 있다.
  • 백엔드/클라 env·커스텀 JWT 는 이미 이 프로젝트를 가리킨다. 커스텀 JWT 는 HS256, front-api·dashboard 가 COMMUNITY_V2_SUPABASE_JWT_SECRET 로 서명한다.
  • 채팅 첨부(ADR-0021)는 R2 key 를 message.attachments 에 저장하고 서빙 URL 을 COMMUNITY_MEDIA_R2_PUBLIC_BASE_URL+key 로 유도한다.

검토한 대안

대안채택 안 한 이유
별도 dev 프로젝트 신설2026-10-08 에 이미 철회된 안(sendbird-exit-plan.md) — 기존 프로젝트를 재사용(클라 env·JWT 가 이미 가리킴)하기로 함. 완전 독립·Free tier 장점은 있으나 기록된 결정을 뒤집을 근거가 약함.
Supabase CLI 마이그레이션 플로우 전면 채택(브랜치가 migrations 소유)브랜치가 supabase/migrations/ 를 Supabase 추적(supabase_migrations.schema_migrations)으로 적용 → 기존 psql 추적과 이중 추적·이중 적용. 런너를 통째로 교체해야 하고 prod CI(psql)와 갈라짐.
같은 R2 버킷 + 환경 키 프리픽스(dev/·prod/)싸지만 격리가 약하고 공개 URL·자격을 공유. dev key 유출이 prod 미디어를 건드릴 수 있음.
GitHub 연동 브랜칭(PR preview 자동)push 마다 Supabase 가 마이그레이션을 자동 재적용 → psql 과 이중화. 영속 dev 환경엔 PR-ephemeral 모델이 과함.

Decision

  1. dev/prod 격리 = Supabase 영속 브랜치. prod = 현재 프로젝트 유지(repoint 안 함), dev = supabase branches create dev --persistent(GitHub 연동 없이 CLI 로만). --with-data 없이 생성해 prod 실데이터를 복제하지 않는다. 브랜치가 자체 DB URL·anon·secret key·JWT secret 발급.
  2. 마이그레이션 = 하이브리드. 브랜칭은 격리 dev DB+키 프로비저닝 용도로만. 적용은 기존 psql apply-migrations.sh 를 브랜치 DB URL 로 겨눠 수행(GitHub 연동을 켜지 않아 push 자동적용 이중화를 피함). prod 는 기존 supabase-migrate.yml(main push) 그대로.
  3. R2 = 별도 버킷+자격 락스텝 분리. ...-dev 버킷 신설. message 행이 R2 key 를 저장하므로 Supabase 와 함께 갈라야 key↔bucket 정합(안 그러면 크로스-환경 404).
  4. env 만으로 환경 전환. 코드가 COMMUNITY_V2_SUPABASE_*·COMMUNITY_MEDIA_R2_* 를 읽으므로 값만 환경별로 분리. 유일한 코드 변경은 native apps/native-app/src/config/env.ts(현재 단일 하드코딩 → 환경분기). 매핑: local·development·qa → dev 브랜치, production·canary·devtools → prod. canary·devtools 는 콘텐츠가 production(실 서버)이라 prod 를 쓴다(API_URL 과 같은 기준). devtools 는 내부 env override 로 dev 전환 시에만 dev.

배선 위치: supabase/config.toml(tooling 전용, 최소), supabase/scripts/apply-migrations.sh(psql), .github/workflows/supabase-migrate.yml(prod), 절차 문서 apps/docs/content/database/community-v2-supabase-environments.mdx.

Consequences

좋아지는 것

  • dev 테스트 데이터·미디어가 prod 와 물리적으로 격리. 통합 채팅 prod 출시 안전.
  • 기존 psql 마이그레이션 자산을 그대로 재사용(러너 교체 없음). prod 경로 무변경.
  • 브랜치가 프로젝트 통째 격리라 리셉션·세금챗도 자동으로 dev/prod 로 갈림.

감수하는 것

  • Supabase CLI·브랜칭 인프라를 새로 들여야 한다(선행 비용). 영속 브랜치는 compute 로 과금.
  • GitHub 연동 없이 supabase branches create 로 만든 브랜치는 저장소의 supabase/migrations/*.sql 을 적용하지 않고 부모(prod)의 Supabase 마이그레이션 이력으로 스키마를 만든다. prod 를 psql 로 쌓았다면 그 이력이 불완전(대개 remote_schema 스냅샷 1개)해 브랜치 스키마가 우리 migrations 와 불일치한다 — HMH-9979 실측: channel(0014)·assessed_prices_unit(0001) 등 psql-only 테이블 누락. 그래서 브랜치를 prod 복제로 신뢰하지 말고 public 스키마를 비우고 migrations 를 전량 재적용해 재구축한다(브랜치는 데이터 없음 → 안전, 비멱등 DDL 도 빈 스키마라 무해). 절차: database/community-v2-supabase-environments 4번.
  • config.toml 을 커밋하므로 supabase config push/db push 오남용 시 prod 설정을 덮을 위험 → 최소 config + 문서 경고로 방어.
  • 리셉션·세금챗 dev 가 dev 브랜치를 보게 되는 영향 확인 필요.

이 결정을 다시 열어야 할 때

  • Supabase 가 브랜치의 마이그레이션 자동적용을 끌 수 있게 되면(hybrid 의 GitHub-연동 회피가 불필요) 재검토.
  • 영속 브랜치 compute 비용이 별도 Free-tier 프로젝트보다 커지면 “별도 프로젝트” 안을 다시 검토.
  • prod 마이그레이션까지 Supabase 러너로 통일하고 싶어지면 psql 스크립트 폐기를 재검토.
Last updated on