0. 시작하기 전에

내용 검토: 2026. 08. 12.

무엇을 다루고 무엇을 다루지 않는가

이 문서는 누구를 위한 것인가

웹 개발 경험은 있는데 Supabase는 처음인 사람
Firebase나 직접 만든 Express/Nest 백엔드를 써본 적이 있는 사람 — 비교 지점이 더 잘 보인다
Next.js + Vercel 조합을 쓰고 있거나 쓸 계획인 사람 — 12–13장이 특히 유용하다
“BaaS를 쓰고 싶은데 종속성이 걱정된다”는 판단을 앞두고 있는 사람 (BaaS = Backend as a Service. 인증·DB·스토리지 같은 백엔드를 직접 만들지 않고 서비스로 빌려 쓰는 방식)

전제하지 않는 것: Postgres 심화 지식, 데브옵스 경험, Deno 경험. 전제하는 것: select와 where가 무엇인지 알고, JavaScript로 HTTP 요청을 보내 본 적이 있다.

다룬다

왜 Supabase를 선택하는가 / 언제 선택하면 안 되는가. 각 기능의 “실체”가 Postgres에서 무엇인지. Auth와 RLS가 맞물리는 방식. Vercel과의 역할 배분과 배포 아키텍처. 실전 운영 — 마이그레이션, 브랜칭, 성능, 비용.

다루지 않는다

Postgres 튜닝 심화 (vacuum, WAL 파라미터 등). Supabase 셀프호스팅 운영. 모바일 SDK(Flutter, Swift) 상세. AI/벡터는 “이런 게 있다” 수준까지만.

읽는 내내 이 셋을 배경에 깔아두면 나머지가 훨씬 빨리 붙는다.

새 API를 배우는 게 아니다. 이미 40년 된 데이터베이스를 네트워크 너머로 안전하게 여는 방법을 배우는 것이다. 그래서 배운 것의 대부분이 Supabase를 떠나도 남는다.

if (user.id !== post.authorId) throw 같은 코드가 SQL 정책(RLS)으로 내려간다. 이 전환이 가장 큰 사고방식의 변화이고, 이 문서에서 가장 많은 분량을 차지한다.

이게 왜 중요한가 — 접근 경로가 늘어나도(REST, Realtime, GraphQL, Edge Function) 규칙은 한 곳에만 존재하기 때문이다.

둘은 경쟁 관계가 아니다. 겹치는 지점은 “서버 코드를 어디에 둘까” 하나뿐이고, 그건 판단 기준만 세우면 된다. 12장의 주제다.

이 생태계도 빠르게 움직인다. 검색으로 찾은 글이 이미 낡았을 가능성이 높다. 각 장에서 다시 짚지만, 지금은 “내 기억이 낡았을 수 있다”는 것만 알면 된다.

항목	지금	옛 정보 (자료에 많이 남아 있음)
API 키	`sb_publishable_...` / `sb_secret_...`	`anon key` / `service_role key` (JWT 형태, 폐기 예정)
API 게이트웨이	호스팅 플랫폼은 Envoy	Kong (로컬·셀프호스팅은 버전에 따라 보일 수 있음)
Next.js 통합	`@supabase/ssr` + Next.js 16 `proxy.ts`	`@supabase/auth-helpers-nextjs` + `middleware.ts`
서버에서 신원 확인	`getClaims()` (서명 로컬 검증)	`getSession()`의 user를 신뢰
JWT 서명	비대칭키(ECC/RSA) + JWKS	프로젝트당 대칭키(HS256) 하나
커넥션 풀러	Supavisor (transaction 모드 `6543`)	PgBouncer 단독
대규모 실시간	트리거 + `realtime.broadcast_changes()`	Postgres Changes만

바뀌지 않은 것도 하나 — 로컬 개발에는 여전히 Docker가 필요하다.

용어	한 줄 설명
PostgREST	테이블·뷰·함수를 자동으로 REST API로 노출해 주는 서버
RLS	Row Level Security. 행 단위 접근 제어. Postgres 네이티브 기능
JWT	JSON Web Token. 로그인 후 발급되는 서명된 토큰. 여기 담긴 `sub`가 곧 사용자 ID
anon / authenticated / service_role	요청이 매핑되는 Postgres 역할 3종
publishable / secret key	클라이언트에 노출해도 되는 키 / 서버 전용 키
Supavisor	Supabase의 커넥션 풀러. 서버리스에서 필수
RPC	데이터베이스 함수 호출. `POST /rest/v1/rpc/<이름>`
migration	스키마 변경을 SQL 파일로 버전 관리한 것
CRUD	Create·Read·Update·Delete. 만들고 읽고 고치고 지우는 기본 4연산
MAU	Monthly Active Users. 월간 활성 사용자 수 — 요금제가 이 단위로 계산된다
DDL	Data Definition Language. `create table`처럼 스키마 자체를 바꾸는 SQL
CTE	Common Table Expression. `with` 절 — 쿼리 중간 결과에 이름을 붙이는 문법

읽기만 해서는 안 붙는다. 로컬 스택을 하나 띄워놓고 보는 것을 전제로 쓰였다.

Supabase CLI — 전역 설치보다 프로젝트 의존성 설치를 권한다

# macOS / Linux
brew install supabase/tap/supabase

# 또는 프로젝트 의존성으로 (공식 문서 권장)
npm install supabase --save-dev

계정 생성 — supabase.com에서 GitHub 로그인. Free 플랜만으로도 이 문서의 거의 모든 내용을 실습할 수 있다
로컬 스택 기동 — 3장에서 자세히 다루지만, 미리 한 번 띄워보면 감이 온다
터미널 창
```
supabase init && supabase start
```

1. 왜 Supabase인가선택의 근거를 먼저 세운다 — Firebase와의 결정적 차이, 쓰면 안 되는 경우, 비용 감각.