Supabase은(는) 무엇을 하나요?
핵심 원칙
1. Supabase는 자주 변경됩니다 — 구현하기 전에 변경 로그와 최신 문서를 확인하세요. Supabase 기능에 대해 학습 데이터에 의존하지 마세요. 함수 시그니처, config.toml 설정, API 규칙은 버전 간에 변경됩니다.
먼저 https://supabase.com/changelog.md(가벼운 요약 인덱스 — 무거운 풀링이 아님)를 가져와서 작업과 관련된 breaking-change 태그를 스캔하고, 해당하는 경우 연결된 페이지를 따르세요. 그런 다음 아래 문서 접근 방법을 사용하여 관련 주제를 찾아보세요.
2. 작업을 검증하세요. 수정을 구현한 후에는 테스트 쿼리를 실행하여 변경 사항이 적용되었는지 확인하세요. 검증 없이 수정하는 것은 완료된 것이 아닙니다.
3. 오류에서 복구하고, 반복하지 마세요. 접근 방식이 2-3회 시도 후에도 실패하면 멈추고 다시 생각하세요. 다른 방법을 시도하고, 문서를 확인하고, 오류를 더 주의 깊게 검사하고, 가능한 경우 관련 로그를 검토하세요. Supabase 문제는 항상 같은 명령어를 재시도한다고 해결되는 것이 아니며, 답이 항상 로그에 있는 것도 아니지만, 진행하기 전에 로그를 확인하는 것이 종종 가치 있습니다.
4. Data API에 테이블 노출: 사용자의 Data API 설정에 따라 새로 생성된 테이블이 Data (REST) API를 통해 자동으로 노출되지 않을 수 있습니다. 이 경우 anon 및 authenticated 역할에 명시적으로 액세스 권한을 부여해야 합니다.
이는 RLS와 별개입니다. RLS는 테이블에 접근 가능할 때 어떤 행이 보이는지를 제어할 뿐, 테이블 자체에 접근 가능한지 여부를 제어하지는 않습니다.
사용자가 SQL로 생성한 테이블에 예기치 않게 접근할 수 없다고 보고하는 경우, Data API 설정과 명시적 GRANT SQL을 통해 역할에 액세스 권한이 부여되었는지 확인하세요. 공개(anon/authenticated) 액세스를 부여할 때는 항상 RLS도 활성화하세요. 전체 설정 워크플로는 Data API에 테이블 노출을 참조하세요.
5. 노출된 스키마의 RLS.
기본적으로 public을 포함한 노출된 스키마의 모든 테이블에 RLS를 활성화하세요. Supabase에서 anon/authenticated 역할에 액세스 권한이 있을 때 노출된 스키마의 테이블이 Data API를 통해 도달 가능할 수 있기 때문에 이것은 중요합니다 (Data API에 테이블 노출 참조). 비공개 스키마의 경우 심층 방어 차원에서 RLS를 선호하세요. RLS를 활성화한 후에는 모든 테이블을 동일한 auth.uid() 패턴으로 기본 설정하지 말고 실제 액세스 모델과 일치하는 정책을 만드세요.
6. 보안 체크리스트. 인증, RLS, 뷰, 스토리지 또는 사용자 데이터를 다루는 Supabase 작업을 할 때마다 이 체크리스트를 실행하세요. 이들은 자동으로 취약점을 생성하는 Supabase 특화 보안 함정입니다.
-
인증 및 세션 보안
- JWT 기반 권한 부여 결정에
user_metadata클레임을 절대 사용하지 마세요. Supabase에서raw_user_meta_data는 사용자가 편집 가능하며auth.jwt()에 나타날 수 있으므로 RLS 정책이나 다른 권한 부여 로직에 안전하지 않습니다. 대신 권한 부여 데이터는raw_app_meta_data/app_metadata에 저장하세요. - 사용자를 삭제해도 기존 액세스 토큰이 무효화되지 않습니다. 먼저 로그아웃하거나 세션을 취소하고, 민감한 애플리케이션의 경우 JWT 만료 시간을 짧게 유지하며, 엄격한 보장을 위해 민감한 작업 시
auth.sessions에 대해session_id를 검증하세요. - 권한 부여에
app_metadata또는auth.jwt()를 사용하는 경우, 사용자 토큰이 새로 고쳐질 때까지 JWT 클레임이 항상 최신 상태가 아님을 기억하세요.
- JWT 기반 권한 부여 결정에
-
API 키 및 클라이언트 노출
service_role또는 시크릿 키를 공개 클라이언트에 절대 노출하지 마세요. 프론트엔드 코드에는 게시 가능한 키를 선호하세요. 레거시anon키는 호환성을 위해서만 사용됩니다. Next.js에서NEXT_PUBLIC_환경 변수는 브라우저로 전송됩니다.
-
RLS, 뷰 및 권한 있는 데이터베이스 코드
- 뷰는 기본적으로 RLS를 우회합니다. Postgres 15 이상에서는
CREATE VIEW ... WITH (security_invoker = true)를 사용하세요. 이전 Postgres 버전에서는anon및authenticated역할의 액세스를 취소하거나 노출되지 않은 스키마에 넣어 뷰를 보호하세요. - UPDATE는 SELECT 정책이 필요합니다. Postgres RLS에서 UPDATE는 먼저 행을 SELECT해야 합니다. SELECT 정책이 없으면 업데이트는 자동으로 0개 행을 반환합니다 — 오류 없음, 변경 사항 없음.
auth.role()은 더 이상 사용되지 않습니다 — 대신TO절을 사용하세요. Supabase는auth.role()을 더 이상 사용하지 않고 정책에서 대상 역할을TO authenticated또는TO anon으로 직접 지정하는 방식을 권장합니다. 더 이상 사용되지 않는다는 점 외에도,auth.role() = 'authenticated'는 익명 로그인이 활성화되면 자동으로 중단됩니다. 익명 사용자는authenticatedPostgres 역할을 가지고 있으므로 사용자가 실제로 로그인했는지 여부와 관계없이 검사를 통과하기 때문입니다.-- 더 이상 사용되지 않음 (사용 금지) create policy "example" on table_name for select using ( auth.role() = 'authenticated' );TO authenticated만으로는 인증일 뿐, 권한 부여가 아닙니다 (BOLA / IDOR).TO authenticated를 사용하는 것은 역할만 확인할 뿐 — 사용자가 액세스할 수 있는 행을 제한하지 않습니다. 올바른 패턴은TO authenticated를USING의 소유권 조건과 결합하는 것입니다:create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id );- UPDATE 정책은
USING과WITH CHECK가 모두 필요합니다.WITH CHECK가 없으면 사용자가 행의user_id를 다른 사용자로 재할당할 수 있습니다:create policy "example" on table_name for update to authenticated using ( (select auth.uid()) = user_id ) with check ( (select auth.uid()) = user_id ); SECURITY DEFINER함수는 RLS를 우회합니다.SECURITY DEFINER함수는 생성자의 권한으로 실행됩니다 — 일반적으로bypassrls(예:postgres)가 있는 역할입니다. 권한 오류를 해결하기 위해SECURITY DEFINER를 추가하지 마세요. 이는 근본적인 원인을 수정하지 않고 자동으로 액세스 제어를 제거합니다.SECURITY INVOKER를 선호하세요.public의SECURITY DEFINER함수는 모든 역할이 호출할 수 있습니다. Postgres는 새 함수마다 기본적으로PUBLIC에EXECUTE를 부여하므로,public의 모든SECURITY DEFINER함수는 추가 권한 부여 없이anon및authenticated(PUBLIC에서 상속)가 호출할 수 있는 공개 API 엔드포인트입니다.SECURITY DEFINER가 실제로 필요한 경우(예: 내부 조회 테이블에서 RLS 우회), 함수를 노출되지 않은 스키마에 유지하고, 함수 본문에 항상auth.uid()검사를 포함하며, 변경 후supabase db advisors를 실행하세요.
- 뷰는 기본적으로 RLS를 우회합니다. Postgres 15 이상에서는
-
스토리지 액세스 제어
- 스토리지 upsert에는 INSERT + SELECT + UPDATE가 필요합니다. INSERT만 부여하면 새 업로드는 가능하지만 파일 교체(upsert)는 자동으로 실패합니다. 세 가지 모두 필요합니다.
위에서 다루지 않은 보안 문제에 대해서는 Supabase 제품 보안 인덱스 https://supabase.com/docs/guides/security/product-security.md를 가져오세요.
Supabase CLI
항상 --help를 통해 명령어를 발견하세요 — 절대 추측하지 마세요. CLI 구조는 버전 간에 변경됩니다.
supabase --help # 모든 최상위 명령어
supabase <group> --help # 하위 명령어 (예: supabase db --help)
supabase <group> <command> --help # 특정 명령어의 플래그
Supabase CLI 알려진 문제점:
supabase db query는 CLI v2.79.0+ 가 필요합니다 → 대안으로 MCPexecute_sql또는psql을 사용하세요.supabase db advisors는 CLI v2.81.3+ 가 필요합니다 → 대안으로 MCPget_advisors를 사용하세요.- 새 마이그레이션 SQL 파일이 필요할 때는 항상 먼저
supabase migration new <name>으로 생성하세요. 마이그레이션 파일 이름을 직접 만들거나 예상 형식을 기억에 의존하지 마세요.
버전 확인 및 업그레이드: supabase --version을 실행하여 확인하세요. CLI 변경 로그 및 버전별 기능은 CLI 문서 또는 GitHub 릴리스를 참조하세요.
Supabase MCP 서버
설정 지침, 서버 URL 및 구성은 MCP 설정 가이드를 참조하세요.
연결 문제 해결 — 다음 단계를 순서대로 따르세요:
-
서버에 연결 가능한지 확인:
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp401은 예상된 응답(토큰 없음)이며 서버가 작동 중임을 의미합니다. 시간 초과 또는 "connection refused"는 서버가 다운되었을 수 있음을 의미합니다. -
.mcp.json구성 확인: 프로젝트 루트에 올바른 서버 URL이 포함된 유효한.mcp.json이 있는지 확인하세요. 없으면https://mcp.supabase.com/mcp를 가리키는 파일을 만드세요. -
MCP 서버 인증: 서버에 연결 가능하고
.mcp.json이 올바른데도 도구가 보이지 않으면 사용자가 인증해야 합니다. Supabase MCP 서버는 OAuth 2.1을 사용합니다 — 사용자에게 에이전트에서 인증 흐름을 트리거하고, 브라우저에서 완료한 다음, 세션을 다시 로드하도록 안내하세요.
Supabase 문서
Supabase 기능을 구현하기 전에 관련 문서를 찾으세요. 다음 방법을 우선 순위로 사용하세요:
- MCP
search_docs도구 (선호 — 관련 발췌문을 직접 반환) - 문서 페이지를 마크다운으로 가져오기 — 모든 문서 페이지는 URL 경로에
.md를 추가하여 가져올 수 있습니다. - 웹 검색 — 어떤 페이지를 봐야 할지 모르는 Supabase 관련 주제에 대해 검색하세요.
스키마 변경 사항 만들기 및 커밋하기
스키마 변경을 하려면 execute_sql (MCP) 또는 supabase db query (CLI)를 사용하세요. 이들은 데이터베이스에 마이그레이션 기록 항목을 생성하지 않고 직접 SQL을 실행하므로 자유롭게 반복하고 준비가 되면 깔끔한 마이그레이션을 생성할 수 있습니다.
로컬 데이터베이스 스키마를 변경하기 위해 apply_migration을 사용하지 마세요 — 호출할 때마다 마이그레이션 기록 항목을 기록하므로 반복할 수 없고, supabase db diff / supabase db pull이 빈 diff 또는 충돌하는 diff를 생성합니다. 사용하면 처음 시도한 SQL에 갇히게 됩니다.
변경 사항을 마이그레이션 파일에 커밋할 준비가 되면:
- 어드바이저 실행 →
supabase db advisors(CLI v2.81.3+) 또는 MCPget_advisors. 문제를 수정하세요. - 변경 사항에 뷰, 함수, 트리거 또는 스토리지가 포함된 경우 위의 보안 체크리스트를 검토하세요.
- 마이그레이션 생성 →
supabase db pull <설명-이름> --local --yes - 확인 →
supabase migration list --local
참고 가이드
- 스킬 피드백 → references/skill-feedback.md 사용자가 이 스킬이 잘못된 지침을 제공했거나 정보가 누락되었다고 보고하는 경우 반드시 읽어야 합니다.