Supabase 브랜칭은 ‘DB용 Git’이 아니라 스키마 변경을 격리하는 안전장치다

• 카테고리: web_app_dev
• 예상 읽기 시간: 10분
• 오늘의 질문: 대시보드나 AI 에이전트가 DB 스키마를 바꾸는 시대에, 우리는 어떤 변경을 바로 production에 적용하지 말아야 할까?
• 핵심 출처:
  • Branching Without Git Is Now The Default - Supabase - 2026-06, 확인일 2026-06-19
  • Branching - Supabase Docs - 문서, 확인일 2026-06-19
  • Branching via the dashboard - Supabase Docs - 문서, 확인일 2026-06-19
  • Working with branches - Supabase Docs - 문서, 확인일 2026-06-19
  • [Public Alpha] Declarative Schema Management with pg-delta - Supabase Changelog - 2026-04, 확인일 2026-06-19
  • supabase/pg-toolbelt - GitHub - GitHub, 확인일 2026-06-19

1. 왜 지금 봐야 하나

웹앱 팀에서 데이터베이스 스키마 변경은 늘 애매한 위치에 있다. 프론트엔드 코드는 PR에서 diff를 보고 리뷰하기 쉽다. 서버 코드도 테스트와 배포 파이프라인을 붙이기 쉽다. 그런데 테이블 컬럼 추가, RLS 정책 수정, 함수 변경, 인덱스 추가, Edge Function 설정 변경은 종종 Supabase Dashboard나 SQL Editor에서 “잠깐” 고쳐진다.

이 “잠깐”이 위험한 이유는 DB 스키마가 제품 상태 그 자체이기 때문이다. 컬럼 하나의 nullable 여부, RLS 정책의 using 조건, 함수의 security definer 여부는 사용자 데이터 접근 방식과 바로 연결된다. 특히 AI 코딩 에이전트가 Supabase MCP 도구로 branch, SQL, migration 작업을 호출할 수 있는 환경에서는 변경 속도가 더 빨라진다. 빠른 실험 자체는 좋은데, 실험과 production의 경계가 흐려지면 사고가 난다.

Supabase는 최근 “Git 없이도 대시보드에서 브랜치를 만들고, SQL Editor/Table Editor로 바꾼 뒤, diff를 검토하고 merge하는” Dashboard Branching을 기본 흐름으로 밀고 있다. 공식 블로그는 Branching without Git이 모든 프로젝트의 기본값이 되었고, Git 기반 브랜칭과 함께 사용할 수 있다고 설명한다. 또 merge diff는 새 schema diff 엔진인 pg-delta가 담당한다고 밝힌다.

오늘의 핵심은 “Supabase가 DB용 Git을 만들었다”가 아니다. 더 정확한 질문은 이것이다. 스키마 변경을 production에 바로 쓰지 않고, 격리된 환경에서 diff·권한·데이터 없음·배포 단계를 확인하는 습관을 어떻게 만들 것인가?

2. 핵심 개념

핵심 개념은 스키마 변경의 격리 단위다.

Git 브랜치는 코드 변경을 격리한다. Supabase 브랜치는 Supabase 프로젝트 변경을 격리한다. 문서 기준 브랜치는 별도의 환경이며, 자체 Supabase instance, API credentials, DB instance, API endpoint, Auth 설정, Storage bucket 등을 가진다. 그래서 preview branch에서 테이블을 만들거나 RLS 정책을 수정해도 main production에는 바로 영향을 주지 않는다.

다만 여기서 중요한 차이가 있다. Supabase 문서는 새 브랜치가 기본적으로 production 데이터를 복사해 시작하지 않는다고 설명한다. 이는 민감한 production 데이터를 보호하기 위한 설계다. 즉 Supabase 브랜치는 “운영 데이터까지 통째로 복제한 sandbox”가 아니라, 주로 schema/config/function 변경을 안전하게 검토하는 preview 환경에 가깝다. 데이터가 필요한 테스트는 seed 파일이나 별도 샘플 데이터 전략이 필요하다.

Dashboard Branching의 흐름은 다음과 같이 단순하다.

1. 대시보드에서 branch를 만든다.
2. branch selector로 현재 작업 대상이 production인지 preview인지 확인한다.
3. SQL Editor, Table Editor, 설정 화면, branch credentials를 통해 변경한다.
4. merge request를 만들고 production과의 diff를 검토한다.
5. production으로 merge한다.

이때 diff가 중요하다. Supabase 블로그는 pg-delta가 tables, columns, RLS policies, functions, triggers, indexes, extensions 같은 Postgres 객체를 비교해 migration statement를 생성한다고 설명한다. 하지만 동시에 pg-delta는 alpha software이고, diff review에서 버그를 발견하면 이슈를 제보해 달라고 말한다.

따라서 실무에서의 원칙은 단순하다. 브랜치가 있다고 안전한 것이 아니라, diff를 읽는 사람이 있어야 안전하다.

3. 최신 이슈와 연결

이번 변화가 흥미로운 이유는 두 가지 흐름이 만났기 때문이다.

첫째, DB 변경이 점점 더 “대시보드 중심”이 되고 있다. 작은 팀은 모든 변경을 로컬 migration 파일에서 시작하지 않는다. Table Editor로 빠르게 필드를 만들고, SQL Editor에서 정책을 실험하고, Auth/Storage/Edge Function 설정을 화면에서 조정한다. Dashboard Branching은 이 현실을 인정한다. GitHub integration이 없어도 branch를 만들고, dashboard 안에서 diff를 보고, 나중에 Git 기반 workflow로 연결할 수 있게 한다.

둘째, AI workflow가 DB 변경에 들어오고 있다. Supabase 블로그는 MCP server를 통해 만들어진 모든 branch가 dashboard branching을 사용한다고 설명한다. AI 도구가 스키마를 실험해야 할 때 branch를 만들고, 변경하고, merge할 수 있다는 뜻이다. 이 흐름은 개발 생산성을 올리지만, 동시에 “AI가 만든 migration diff를 누가 검토하는가?”라는 질문을 남긴다.

셋째, schema diff 엔진 자체가 제품 품질의 일부가 됐다. Supabase changelog는 CLI에 pg-delta와 experimental declarative schema workflow가 들어왔고, SQL 파일을 desired state로 두고 migration을 생성하는 방향을 설명한다. 즉 앞으로는 사람이 매번 imperative migration을 직접 쓰는 방식과, 도구가 schema diff를 생성하는 방식이 함께 쓰일 가능성이 높다.

이제 웹앱 개발자는 “마이그레이션 파일이 있느냐”만 볼 수 없다. 어떤 환경에서 변경했는지, diff 엔진이 무엇을 생성했는지, 누가 읽었는지, seed 없는 branch에서 어떤 테스트를 했는지까지 봐야 한다.

4. 개발자 관점 해석

작은 웹앱 팀에게 Supabase 브랜칭은 세 가지 규칙으로 해석하는 것이 좋다.

1) Production SQL Editor를 실험 공간으로 쓰지 않는다

긴급 hotfix가 아닌 이상 schema 변경은 preview branch에서 먼저 한다. 특히 다음 변경은 production에서 바로 실험하지 않는 것이 좋다.

• RLS policy 추가/수정/삭제
• security definer 함수 변경
• public API로 노출되는 table/view 변경
• nullable에서 not null로 바꾸는 변경
• unique/index 추가처럼 lock이나 성능 영향을 줄 수 있는 변경
• Edge Function 삭제/이름 변경/secret 변경

2) Branch는 데이터 복제본이 아니라 변경 검토 환경이다

Supabase 문서는 새 branch가 production data 없이 시작한다고 설명한다. 그래서 “preview에서 에러가 안 났다”는 말은 “실제 운영 데이터 분포에서도 안전하다”와 다르다. 예를 들어 not null 컬럼 추가는 빈 seed 데이터에서는 성공하지만 production에 null row가 있으면 실패할 수 있다. unique constraint도 샘플 데이터에서는 통과하지만 production 중복 데이터 때문에 막힐 수 있다.

따라서 branch 테스트에는 최소 seed 세트가 필요하다.

• 정상 사용자 1명
• 권한이 낮은 사용자 1명
• owner/admin 사용자 1명
• soft deleted row
• nullable edge case row
• 중복 가능성이 있는 row
• RLS로 보이면 안 되는 row

3) Diff review는 “SQL 문법 확인”이 아니라 “권한과 제품 상태 확인”이다

pg-delta가 migration statement를 만들어도 개발자는 아래를 봐야 한다.

• 새 테이블에 RLS가 켜졌는가?
• anon, authenticated, service role, custom role의 접근 의도는 맞는가?
• 정책이 permissive OR 결합으로 너무 넓어지지 않았는가?
• 함수 search_path, volatility, security definer 설정은 안전한가?
• column default와 not null 변경이 기존 데이터에 적용 가능한가?
• index 추가가 production 부하를 만들 수 있는가?
• Edge Function 변경이 branch update/merge 과정에서 덮어쓰기될 수 있는가?

문서의 Dashboard Branching 제한도 함께 봐야 한다. custom role이 branch creation에 잡히지 않을 수 있고, branch는 main으로만 merge되며, out-of-date branch를 update할 때 edge functions가 overwrite될 수 있고, migration conflict는 preview branch에서 수동으로 해결해야 한다. 이 제한을 모르면 “브랜치가 있으니 안전하다”는 착각이 생긴다.

5. 내 프로젝트에 적용할 체크포인트

오늘 바로 팀 규칙으로 바꿀 수 있는 체크포인트는 다음과 같다.

• Supabase Dashboard 상단 branch selector를 코드 리뷰 체크리스트에 넣는다. 스크린샷이나 작업 로그에 main / PRODUCTION인지 preview인지 남긴다.
• production SQL Editor 직접 실행을 금지할 변경 목록을 정한다. RLS, function, destructive DDL은 기본적으로 branch에서 시작한다.
• merge request에서 schema diff를 읽을 담당자를 정한다. AI가 만든 diff도 사람이 읽는다.
• seed 파일이나 seed SQL을 만든다. 특히 RLS와 constraint edge case 데이터를 포함한다.
• branch credentials를 .env.preview처럼 분리한다. local app이 production key를 물고 preview 테스트를 하지 않게 한다.
• Git 기반 migration workflow를 쓰는 팀은 dashboard 변경 후 supabase db pull로 migration 파일을 남기는 절차를 정한다.
• pg-delta나 declarative schema workflow를 쓸 때는 alpha/experimental 상태를 감안해 generated migration을 반드시 리뷰한다.
• branch update 시 Edge Functions overwrite 가능성을 알고, 함수 변경은 별도 체크리스트로 확인한다.

6. 오늘 10분 액션

10분만 투자한다면 아래 순서로 해보자.

1. Supabase Dashboard를 열고 현재 프로젝트의 branch selector 위치를 확인한다.
2. production에서 바로 실행하면 위험한 SQL 예시 3개를 적는다.
   • RLS policy 변경
   • alter table ... set not null
   • function 권한 변경
3. preview branch를 만들 수 있는 권한이 누구에게 있는지 확인한다.
4. 최근 1개월 DB 변경 중 “branch에서 먼저 했어야 했던 것”을 하나 고른다.
5. 그 변경을 리뷰했다면 어떤 diff 항목을 봐야 했는지 적는다.
6. seed 데이터에 “권한이 낮은 사용자”와 “보이면 안 되는 row”가 있는지 확인한다.

오늘의 목표는 브랜칭 기능을 완벽히 도입하는 것이 아니다. 목표는 “DB 변경도 코드처럼 격리하고 diff로 리뷰해야 한다”는 감각을 팀에 심는 것이다.

7. 더 볼 자료

• Supabase Branching docs
• Branching via the dashboard
• Working with branches
• Declarative database schemas
• pg-toolbelt / pg-delta

중복 회피 메모

로컬 content/generated와 Supabase 최근 web_app_dev 글을 확인했다. 최근 글은 에이전트 친화적 페이지의 content negotiation, React Compiler 렌더링 계약, Supabase AI 에이전트 권한표, Next.js Cache Components, Supabase Auth/RLS/Realtime, Hono 보안 릴리스를 다뤘다. 이번 글은 Supabase를 다시 다루지만 인증·RLS 정책 작성·Realtime·AI 도구 권한표가 아니라, Dashboard Branching과 pg-delta를 계기로 DB 스키마 변경을 production에서 분리하고 diff/seed/merge 제한을 검토하는 배포 안전장치 관점에 집중했다.