Skip to Content
Databasecommunity-v2 Supabase 환경(dev/prod)

community-v2 Supabase 환경(dev/prod)

채팅(DM·그룹)·리셉션 세션·세금챗 등이 사는 community-v2 Supabase 프로젝트(ref rvbpczkrxvzlszpdxady)의 dev/prod 환경 격리 절차다. 웹 DB(Neon, DB 홈)·백엔드 DB(RDS)와는 별개다.

배경·결정 근거는 ADR-0022 참고. 상위 계획: HMH-9973.

모델 요약

  • prod = 현재 프로젝트(rvbpczkrxvzlszpdxady) 그대로. 라이브 DM·리셉션 데이터가 여기 있으므로 repoint 하지 않는다.
  • dev = Supabase 영속 브랜치. 프로젝트 통째의 격리 복제라 자체 DB URL·anon key·secret key·JWT secret 을 발급받는다.
  • 마이그레이션 = 하이브리드: 브랜치는 격리된 dev DB+키 프로비저닝 용도로만 쓴다. 마이그레이션 적용은 기존 supabase/scripts/apply-migrations.sh(psql) 가 소유한다. 그래서 GitHub 연동을 켜지 않는다 — 켜면 Supabase 가 push 마다 supabase/migrations/ 를 자체적으로 재적용해 psql 추적(_supabase_sql_migrations)과 이중화된다.

선행 조건

  • 프로젝트가 Pro 플랜 이상이어야 브랜칭을 쓸 수 있다. 영속 브랜치는 시간당 compute 로 과금된다.
  • Supabase CLI 설치:
brew install supabase/tap/supabase # 또는: npx supabase <command> supabase --version
  • supabase login (개인 access token). 이건 계정 작업이라 로컬에서 직접 실행한다.

레포 루트의 supabase/config.toml 이 project_id 를 들고 있다. prod 프로젝트에 link 한다(브랜치는 이 프로젝트에서 파생된다).

supabase link --project-ref rvbpczkrxvzlszpdxady
  • link 시 CLI 가 config.toml 의 [db] major_version 과 remote 를 비교한다. 불일치 경고가 뜨면 remote 에서 SHOW server_version; 을 확인해 config.toml 의 값을 바로잡는다.
  • config.toml 은 브랜치/마이그레이션 tooling 전용이다. supabase config push · supabase db push 를 prod 에 실행하지 않는다(prod 마이그레이션은 psql 워크플로가 소유).

2. 영속 dev 브랜치 생성

supabase branches create dev --persistent --region ap-northeast-2
  • --persistent: PR 머지/종료와 무관하게 유지(staging/dev 용). auto-pause·auto-delete 안 됨.
  • --with-data 를 쓰지 않는다: prod 데이터(DM·리셉션 등 실사용자 데이터)를 dev 로 복제하지 않는다. 스키마만 복제된다.
  • ⚠️ GitHub 연동 없이 create 한 브랜치는 저장소의 supabase/migrations/*.sql 을 적용하지 않고 부모(prod)의 Supabase 마이그레이션 이력으로 스키마를 만든다. prod 를 psql 로 쌓았다면 그 이력이 불완전해 브랜치 스키마가 우리 migrations 와 불일치한다(테이블 누락, HMH-9979 실측). 그래서 브랜치 스키마는 신뢰하지 말고 4번에서 재구축한다.
  • --region 은 prod 와 같은 서울 리전.

브랜치 정보 확인:

supabase branches list supabase branches get dev

3. dev 브랜치 자격 획득

dev 브랜치의 DB 연결 문자열 · API URL · anon key · secret key · JWT secret 을 확보한다. supabase branches get dev 또는 Supabase 대시보드(브랜치 선택 → Project Settings)에서 얻는다.

  • DB 연결 문자열은 Session pooler(IPv4) URI 를 쓴다 — Direct(IPv6 전용)는 GitHub 러너·일부 환경에서 Network is unreachable 로 실패한다(prod 마이그레이션에서 겪은 이슈와 동일).
  • 이 값들은 시크릿이다. .env.shared 등 커밋 안 되는 곳에만 두고, 공유 시엔 출력하지 않는다.

4. dev 브랜치 스키마 재구축 (하이브리드)

⚠️ 중요(실측): GitHub 연동 없이 만든 브랜치는 부모의 Supabase 마이그레이션 이력으로 스키마를 만든다. 그런데 prod 스키마는 우리가 psql 로 쌓아서 Supabase 이력이 불완전하다(대개 remote_schema 스냅샷 1개뿐). 그래서 브랜치 스키마가 우리 supabase/migrations/ 와 불일치한다 — 실제로 channel(0014)·assessed_prices_unit(0001) 등 psql 로만 적용한 것들이 누락된다(HMH-9979 에서 실측). 따라서 브랜치를 prod 복제로 신뢰하지 말고, public 스키마를 비우고 우리 migrations 를 전량 재적용한다(브랜치는 데이터가 없으니 안전).

⚠️ 아래는 파괴적(drop schema)이다. 가드가 출력만 하고 넘어가면 안 되므로, channel 이 있으면(= prod 의심) drop 이 아예 실행되지 않도록 if/else 로 자동 중단한다. DEV_URL 에 prod 문자열을 넣는 사고를 이 가드가 막는다.

DEV_URL='<dev 브랜치 Session pooler URL>' # 안전가드 + 재구축: channel 이 있으면(prod 는 보유, 신규 dev 브랜치는 미보유) 즉시 중단. if [ "$(psql "$DEV_URL" -tAc "select to_regclass('public.channel') is not null")" != "f" ]; then echo "❌ ABORT: 이 연결에 channel 이 있거나 조회 실패 — prod 위험. 중단." else # public 스키마 재구축 + 기본 grant + ⚠️ Supabase default privileges 복원(테이블 생성 전!) # drop schema 가 Supabase 기본 default privileges 를 날린다. 복원하지 않으면 migration 테이블이 # anon/authenticated 에게 grant 를 못 받아 PostgREST 가 403(permission denied)을 낸다 # (행 접근은 RLS 가 지키므로, 테이블 grant 를 넓게 줘도 안전 — prod 와 동일한 posture). psql "$DEV_URL" -v ON_ERROR_STOP=1 -c " drop schema public cascade; create schema public; grant usage on schema public to postgres, anon, authenticated, service_role; grant create on schema public to postgres, service_role; alter default privileges in schema public grant all on tables to anon, authenticated, service_role; alter default privileges in schema public grant all on sequences to anon, authenticated, service_role; alter default privileges in schema public grant execute on functions to anon, authenticated, service_role;" # migrations 전량 재적용(빈 스키마라 비멱등 DDL 도 안전). 테이블은 위 default privileges 를 # 상속하고, migration 안의 revoke(예: 0014 가 authenticated 의 channel insert 회수)가 그 위에 적용된다. SUPABASE_DB_URL="$DEV_URL" bash supabase/scripts/apply-migrations.sh fi

이후 신규 마이그레이션은 SUPABASE_DB_URL="$DEV_URL" bash supabase/scripts/apply-migrations.sh 로 적용된다(추적 테이블 기준 미적용분만).

5. 시드(선택)

그룹 채팅 dev 시드가 필요하면:

psql '<dev 브랜치 Session pooler URL>' -f supabase/scripts/seed-ws3b-group.sql

6. 이후 단계(별도 PR)

브랜치가 서면 HMH-9973 계획의 나머지가 이어진다:

  • env 등록: front-api·dashboard·chat-api 의 Vercel Preview 타깃에 dev 브랜치 값(COMMUNITY_V2_SUPABASE_*, COMMUNITY_MEDIA_R2_*) 등록 + GitHub dev 환경 SUPABASE_DB_URL.
  • native env.ts: 현재 하드코딩(단일 Supabase URL/anon)을 환경분기로. 매핑은 local·development·qa → dev, production·canary·devtools → prod(canary·devtools 는 콘텐츠가 production=실 서버라 prod; devtools 는 내부 env override 로만 dev 전환).
  • R2 별도 버킷: ...-dev 버킷+자격을 Supabase 와 락스텝으로 분리.
  • 마이그레이션 워크플로 2-타깃화(HMH-9980 구현): supabase-migrate.yml 이 develop push → dev 브랜치(environment supabase-migrate-dev), main push → prod(environment supabase-migrate). ⚠️ dev 자동화가 돌려면 GitHub Environment supabase-migrate-dev(deployment branch 정책=develop) + 시크릿 SUPABASE_DB_URL=dev 브랜치 Session pooler URL 등록이 선행돼야 한다.
  • prod 정리: repoint 검증 후 prod 의 통합채팅 테스트 행 truncate + prod 버킷 테스트 오브젝트 삭제.

주의

  • GitHub 연동 브랜칭을 켜지 않는다(위 하이브리드 이유). 영속 dev 브랜치는 CLI 로만 관리한다.
  • prod 프로젝트에 config push/db push/db reset --linked(파괴적) 금지. prod DDL 은 .github/workflows/supabase-migrate.yml(main push, psql) 만 수행한다. (config.toml 의 [db.migrations] enabled=false 는 Branching 자동 마이그레이션만 막을 뿐 이 CLI 명령들은 못 막는다.)
Last updated on