Supabase CLI — 로컬 개발 환경 구성 도구

프로덕션 Supabase 프로젝트에 직접 연결해 개발하면 실수 한 번이 실제 데이터를 망가뜨린다. Supabase CLI는 Docker 기반으로 로컬에서 Auth, Storage, Edge Functions, PostgreSQL을 통째로 띄워 안전한 개발 루프를 만든다. Migration 파일로 스키마를 버전 관리하고, 타입 자동 생성까지 지원해 풀스택 개발 흐름을 하나의 도구로 통합한다.

설치 및 프로젝트 초기화

# macOS
brew install supabase/tap/supabase

# npm (크로스 플랫폼)
npm install -g supabase

supabase init

supabase init을 실행하면 프로젝트 루트에 supabase/ 디렉터리가 생성된다.

supabase/
├── config.toml        # 로컬 환경 설정
├── migrations/        # SQL migration 파일
└── seed.sql           # 초기 데이터

config.toml — 포트, Auth 설정, Storage 버킷 등 로컬 Supabase 인스턴스의 동작을 제어하는 설정 파일.

supabase start — 로컬 스택 실행

supabase start

내부적으로 Docker Compose로 여러 컨테이너를 순서대로 기동한다.

supabase start
         │
         ▼
┌────────────────────────────┐
│  PostgreSQL  (54322)       │
│  GoTrue / Auth  (54321)    │
│  PostgREST  (54321/rest)   │
│  Realtime                  │
│  Storage                   │
│  Studio  (54323)           │
└────────────────────────────┘
         │
         ▼
   API URL: http://localhost:54321
   Studio:  http://localhost:54323

실행 후 출력되는 anon key와 service_role key를 .env.local에 복사해 앱과 연결한다.

Migration 관리

스키마 변경은 SQL 파일로 관리한다. 수동 작성과 자동 생성 두 가지 방식을 지원한다.

# 새 migration 파일 생성
supabase migration new create_posts_table

# 로컬 DB에 migration 적용
supabase db reset

supabase db reset은 DB를 초기화하고 migrations/의 파일을 순서대로 재실행한 뒤 seed.sql을 적용한다.

Migration — 스키마 변경 이력을 타임스탬프 순서로 기록한 SQL 파일 모음. 팀원 간 동일한 스키마 상태를 보장한다.

프로덕션에 배포할 때는 db push를 사용한다.

supabase db push

명령어	대상	동작
`db reset`	로컬	초기화 후 전체 migration 재실행
`db push`	프로덕션	미적용 migration만 순차 실행

TypeScript 타입 자동 생성

DB 스키마에서 TypeScript 타입을 직접 생성한다. 수동으로 타입을 작성할 필요가 없다.

supabase gen types typescript --local > src/types/supabase.ts

생성된 파일을 Supabase 클라이언트에 제네릭으로 주입하면 쿼리 결과가 자동으로 타입을 갖는다.

import { createClient } from '@supabase/supabase-js'
import type { Database } from './types/supabase'

const supabase = createClient<Database>(url, key)

// posts 테이블 타입이 자동 추론됨
const { data } = await supabase.from('posts').select('*')

gen types — 로컬 또는 원격 DB의 스키마를 읽어 테이블, 뷰, 함수 시그니처를 TypeScript 인터페이스로 변환하는 명령어.

로컬 ↔ 프로덕션 연동

# 프로덕션 프로젝트와 연결
supabase link --project-ref <project-id>

# 프로덕션 스키마를 로컬 migration으로 가져오기
supabase db pull

db pull은 이미 프로덕션에 존재하는 스키마를 migration 파일로 역생성해 로컬과 동기화할 때 사용한다. 기존 프로젝트에 CLI를 도입할 때 출발점이 된다.