Supabase 사용법 입문 — 프로젝트 생성부터 DB 연결, 클로드 코드 MCP 연동까지

슈퍼베이스를 한마디로 말하면 PostgreSQL 데이터베이스 위에 백엔드에서 매번 손으로 짜야 했던 기능들을 미리 얹어 둔 도구입니다. 데이터베이스만 주는 게 아니라, 그 위에 로그인 인증, 파일 스토리지, 실시간 구독, 그리고 테이블을 만들면 자동으로 생기는 REST·GraphQL API까지 한 묶음으로 제공합니다. 그래서 서버 코드를 거의 짜지 않고도 프런트엔드 앱에서 바로 데이터를 읽고 쓸 수 있습니다.

흔히 파이어베이스(Firebase) 대안으로 소개되지만, 가장 큰 차이는 밑바탕이 진짜 관계형 데이터베이스인 PostgreSQL이라는 점입니다. NoSQL 문서 구조가 아니라 SQL로 테이블·조인·트랜잭션을 그대로 쓸 수 있어서, 나중에 데이터가 복잡해져도 설계가 무너지지 않습니다. 아래 표로 입문자가 자주 헷갈리는 구성 요소를 정리했습니다.

저는 처음에 단순한 방문자 수 기록 테이블 하나를 붙이려고 슈퍼베이스를 골랐는데, 인증과 스토리지가 같이 따라오니 사이트가 늘어날수록 백엔드를 새로 짤 일이 거의 없어졌습니다. 1인 개발자에게는 짜야 할 코드의 양 자체가 줄어드는 게 가장 큰 이점이었습니다.

슈퍼베이스 콘솔(supabase.com)에 깃허브(GitHub) 계정으로 로그인하면 조직(Organization)부터 만들게 됩니다. 조직은 결제와 멤버를 묶는 단위이고, 그 안에 실제 데이터베이스인 프로젝트(Project)를 생성합니다. 무료 플랜에서는 보통 조직당 프로젝트 2개까지 활성 상태로 둘 수 있습니다.

프로젝트를 만들 때 입력하는 항목 중 입문자가 가장 자주 실수하는 두 가지를 짚겠습니다.

1. 데이터베이스 비밀번호 — 프로젝트 생성 시 정하는 이 비밀번호는 PostgreSQL에 직접 접속할 때 쓰는 값입니다. 한 번 닫으면 화면에 다시 보여 주지 않으니, 만드는 순간 비밀번호 관리자에 저장해 두는 게 안전합니다. 잊어버리면 설정에서 재설정해야 합니다.
2. 리전(Region) 선택 — 데이터가 물리적으로 어느 지역 서버에 저장될지 정하는 값입니다. 한국 사용자 대상 서비스라면 일본 도쿄(Northeast Asia, Tokyo) 리전을 고르는 편이 응답 지연이 가장 짧습니다. 한 번 정한 리전은 나중에 바꾸기 까다로우니 처음에 신중하게 고릅니다.

프로젝트가 만들어지면 좌측 메뉴에 Table Editor, SQL Editor, Authentication, Storage 등이 보입니다. 이제 데이터를 담을 테이블을 만들 차례입니다.

테이블은 두 가지 방법으로 만들 수 있습니다. 화면에서 클릭으로 만드는 Table Editor 방식과, SQL Editor에 직접 쿼리를 붙여 넣는 방식입니다. 처음에는 Table Editor가 직관적이지만, 컬럼 구조를 정확히 통제하려면 SQL이 더 빠르고 실수가 적습니다. 아래는 방문자 기록을 담는 간단한 테이블을 SQL로 만드는 예시입니다.

여기서 입문자가 반드시 알아야 할 개념이 행 수준 보안(RLS, Row Level Security)입니다. 슈퍼베이스는 테이블을 만들면 누구나 접근할 수 있는 자동 API를 함께 열어 줍니다. 그래서 RLS를 켜지 않으면 anon 키만 알면 외부에서 데이터를 통째로 읽거나 쓸 수 있습니다. 공개해도 되는 테이블이라도 RLS는 켜 두고, 어떤 동작을 허용할지 정책(Policy)으로 명시하는 게 기본입니다.

위 쿼리를 SQL Editor에 붙여 넣고 실행(Run)하면 테이블이 생기고, 동시에 RLS가 켜진 채로 읽기만 허용됩니다. 쓰기 정책을 따로 만들지 않았으므로 anon 키로는 데이터를 추가할 수 없습니다. 데이터 삽입은 뒤에서 다룰 service_role 키를 쓰는 서버 쪽 코드에서만 가능하게 막아 두는 식입니다. 이렇게 읽기와 쓰기 권한을 분리해 두는 습관이 보안 사고를 크게 줄여 줍니다.

테이블이 만들어지면 Table Editor에서 행을 직접 추가해 데이터가 들어가는지 확인해 보고, 다음 단계인 앱 연결로 넘어갑니다.

앱에서 슈퍼베이스에 접속하려면 두 가지 값이 필요합니다. 프로젝트 URL과 키(Key)입니다. 콘솔의 Project Settings → API 메뉴에서 확인할 수 있고, 키는 성격이 다른 두 종류가 있습니다. 이 둘을 구분하는 게 입문 단계에서 가장 중요합니다.

핵심 원칙은 이렇습니다. 브라우저로 내려가는 코드에는 anon 키만 쓰고, service_role 키는 절대 프런트엔드 번들이나 깃허브에 올리지 않습니다. service_role 키는 RLS를 통째로 무시하는 전권 키라, 유출되면 데이터베이스 전체가 외부에 열립니다. 그래서 환경 변수 이름도 명확히 구분해 둡니다.

패키지를 설치하고 클라이언트를 만드는 코드는 다음과 같습니다. 먼저 슈퍼베이스 자바스크립트 SDK를 설치합니다.

이렇게 만든 클라이언트로 앞서 만든 pageviews 테이블에서 데이터를 읽으려면 const { data, error } = await supabase.from("pageviews").select("*").order("visited_at", { ascending: false }).limit(10) 처럼 메서드를 체이닝합니다. SQL을 직접 쓰지 않아도 select·insert·update·delete가 메서드로 제공되고, RLS 정책이 그대로 적용되므로 anon 키로는 정책이 허용한 동작만 통과합니다. 데이터를 추가·수정하는 쓰기 작업은 API 라우트(서버 코드)에서 service_role 키로 별도 클라이언트를 만들어 처리하면 안전합니다.

여기서부터가 제가 12개 사이트를 운영하면서 실제로 가장 많이 쓰는 부분입니다. 클로드 코드(Claude Code)에 슈퍼베이스 MCP(Model Context Protocol) 서버를 연결하면, 콘솔을 열지 않고도 터미널에서 자연어로 테이블 구조를 묻고 SQL을 만들고 데이터를 확인할 수 있습니다. MCP는 클로드 코드 같은 AI 도구가 외부 서비스에 안전하게 접근하도록 표준화한 연결 규약이라고 보면 됩니다.

연결 순서는 세 단계입니다.

1. 슈퍼베이스 개인 액세스 토큰(Personal Access Token) 발급 — 콘솔의 Account → Access Tokens에서 새 토큰을 만듭니다. 이 토큰은 한 번만 보이니 바로 복사해 둡니다.
2. 프로젝트 ref 확인 — Project Settings → General에서 프로젝트 참조 ID(project-ref)를 복사합니다. URL에 들어 있는 그 값입니다.
3. 클로드 코드에 MCP 서버 등록 — claude mcp add 명령으로 슈퍼베이스 MCP 서버를 추가합니다.

등록이 끝나면 클로드 코드 세션에서 자연어로 요청할 수 있습니다. 예를 들어 pageviews 테이블에서 가장 많이 방문된 경로 상위 10개를 보여 줘 라고 하면, 클로드 코드가 MCP를 통해 테이블 구조를 읽고 SQL을 만들어 실행한 뒤 결과를 정리해 줍니다. 콘솔과 코드 에디터를 오가지 않아도 되니 1인 개발에서 데이터 확인 속도가 확연히 빨라집니다. MCP 연결의 더 깊은 개념과 다른 서버 연동은 클로드 코드 가이드 시리즈에서 별도로 다룹니다.

입문 단계에서는 무료 플랜으로 충분합니다. 다만 무료 플랜에는 두 가지 제약이 있어서 미리 알아 두면 당황하지 않습니다. 첫째, 일정 기간 활동이 없으면 프로젝트가 일시정지(pause)됩니다. 토이 프로젝트를 며칠 안 들어가면 멈춰 있을 수 있는데, 콘솔에서 다시 켜면(restore) 복구됩니다. 둘째, 데이터베이스 용량과 월 전송량에 한도가 있어서, 트래픽이 늘면 초과 전에 유료 플랜으로 올라가야 합니다.

유료 Pro 플랜은 2026년 6월 기준 월 25달러부터입니다. 한국 카드로 결제하면 표기 금액에 부가가치세(VAT) 10%가 더해지고, 카드사 환율과 해외 결제 수수료가 적용돼 원화 청구액은 매달 조금씩 달라집니다. 환율을 1,350원 안팎으로 가정하면 VAT 포함 약 27.5달러가 대략 3만 7천 원대에서 빠지는 식인데, 정확한 금액은 결제 후 카드 명세서에서 확인하시는 게 맞습니다. 정지 없이 항상 켜져 있어야 하는 서비스를 운영한다면 그 시점이 유료 전환의 손익분기라고 보면 됩니다. 요금과 한도의 정확한 수치는 슈퍼베이스 공식 요금 페이지에서 최신 값을 확인하시길 권장합니다.

제가 직접 겪었거나 주변에서 반복해 본 실수들을 모았습니다. 셋업 직후 이 목록을 한 번 점검하면 사고를 거의 막을 수 있습니다.

• RLS를 안 켰다 — 테이블을 만들고 RLS 없이 두면 anon 키로 외부에서 데이터를 다 읽고 쓸 수 있습니다. 모든 테이블에 RLS를 켜고 정책을 명시하는 게 기본입니다.
• service_role 키를 깃허브에 올렸다 — .env 파일을 .gitignore에 넣지 않아 키가 공개 저장소에 노출되는 사고가 흔합니다. 노출됐다면 즉시 키를 재발급합니다.
• NEXT_PUBLIC 접두사 혼동 — service_role 키에 NEXT_PUBLIC을 붙이면 브라우저로 새어 나갑니다. anon 키에만 붙입니다.
• 리전을 멀리 골랐다 — 한국 사용자 서비스인데 미국 리전을 고르면 응답이 눈에 띄게 느려집니다. 처음에 도쿄 리전을 고릅니다.
• 무료 프로젝트 일시정지를 장애로 오해 — 며칠 안 들어가 멈춘 프로젝트를 버그로 착각하기 쉽습니다. 콘솔에서 restore만 누르면 됩니다.

참고 자료

• Supabase 공식 시작하기 가이드 (supabase.com/docs) — 프로젝트 생성·프레임워크별 연결 튜토리얼
• Supabase MCP 서버 공식 문서 — 클로드 코드·커서 등 AI 도구 연동 설정
• 행 수준 보안(RLS) 공식 가이드 — 정책 작성과 키별 권한 동작