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. 보안 체크리스트. auth, RLS, 뷰, 스토리지 또는 사용자 데이터와 관련된 Supabase 작업을 수행할 때는 이 체크리스트를 실행하십시오. 이는 조용히 취약점을 생성하는 Supabase 특정 보안 함정입니다.
-
인증 및 세션 보안
- JWT 기반 권한 부여 결정에
user_metadata클레임을 절대 사용하지 마십시오. Supabase에서raw_user_meta_data는 사용자가 편집할 수 있으며auth.jwt()에 나타날 수 있으므로 RLS 정책이나 다른 권한 부여 로직에 사용하기에 안전하지 않습니다. 대신raw_app_meta_data/app_metadata에 권한 부여 데이터를 저장하십시오. - 사용자를 삭제해도 기존 액세스 토큰이 무효화되지 않습니다. 먼저 로그아웃하거나 세션을 취소하고, 민감한 앱의 경우 JWT 만료 시간을 짧게 유지하며, 엄격한 보장을 위해 민감한 작업에서
session_id를auth.sessions에 대해 검증하십시오. - 권한 부여를 위해
app_metadata또는auth.jwt()를 사용하는 경우 JWT 클레임은 사용자의 토큰이 새로 고쳐질 때까지 항상 최신 상태가 아님을 기억하십시오.
- JWT 기반 권한 부여 결정에
-
API 키 및 클라이언트 노출
- 퍼블릭 클라이언트에
service_role또는 시크릿 키를 절대 노출하지 마십시오. 프론트엔드 코드에는 게시 가능한 키를 선호하십시오. 레거시anon키는 호환성을 위해서만 사용됩니다. Next.js에서NEXT_PUBLIC_으로 시작하는 모든 env 변수는 브라우저로 전송됩니다. - Management API, CLI 및 MCP 서버에는 범위가 지정된 개인 액세스 토큰을 사용하십시오. 클래식 개인 액세스 토큰은 모든 조직 및 프로젝트에 대한 사용자의 전체 계정 액세스 권한을 전달합니다. 스크립트, CI 및 에이전트의 경우 사용자가 작업에 필요한 조직, 프로젝트 및 권한으로 제한된 범위 지정 토큰을 만들도록 하십시오. 개인 액세스 토큰 가이드에는 각 Management API 엔드포인트 및 MCP 도구에 필요한 권한이 나열되어 있습니다. 추측하지 말고 거기서 권한을 찾으십시오.
- 퍼블릭 클라이언트에
-
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 이상에서는
-
스토리지 액세스 제어
- Storage upsert에는 INSERT + SELECT + UPDATE가 필요합니다. INSERT만 허용하면 새 업로드는 가능하지만 파일 교체(upsert)는 조용히 실패합니다. 세 가지 모두 필요합니다.
-
종속성 및 공급망 보안
- Supabase 패키지(
supabase-js,@supabase/ssr,supabase-py등)를 설치할 때는 항상 패키지 버전을 고정하고 잠금 파일을 커밋하십시오. 전체 체크리스트는 npm 보안 가이드를 참조하십시오.
- Supabase 패키지(
위에서 다루지 않은 보안 문제의 경우 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사용supabase login의 브라우저 흐름은 전체 계정 액세스 권한이 있는 클래식 토큰을 생성합니다. CI에서는 대신SUPABASE_ACCESS_TOKEN을 범위가 지정된 개인 액세스 토큰으로 설정하십시오. 저장된 로그인보다 우선합니다. 데이터베이스 암호로 연결하는 명령어(--password또는SUPABASE_DB_PASSWORD, 예:supabase db push)는 토큰의 권한에 의해 제한되지 않습니다.- 명령형 마이그레이션 프로젝트에서는 먼저
supabase migration new <name>을 사용하여 새 수동 마이그레이션 파일을 만드십시오. 마이그레이션 파일 이름을 임의로 만들거나 예상 형식을 기억에 의존하지 마십시오. 선언적 스키마 프로젝트는supabase/schemas/에서 마이그레이션을 생성합니다. 아래 "스키마 변경 및 커밋"을 참조하십시오.
버전 확인 및 업그레이드: 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을 사용합니다. 사용자에게 에이전트에서 인증 흐름을 트리거하고 브라우저에서 완료한 다음 세션을 다시 로드하도록 지시하십시오. 브라우저 흐름을 실행할 수 없는 CI 또는 기타 환경에서는 대신Authorization: Bearer헤더에 범위가 지정된 개인 액세스 토큰을 전달하십시오. -
범위 지정 토큰 권한 확인: 범위가 지정된 개인 액세스 토큰을 사용하는 동안 도구가 "You do not have permission to perform this action"과 함께 실패하면 토큰에 해당 도구의 권한이 없거나 프로젝트가 토큰의 범위를 벗어난 것입니다. 개인 액세스 토큰 가이드에서 도구의 필수 권한을 확인하십시오.
Supabase 문서
Supabase 기능을 구현하기 전에 관련 문서를 찾으십시오. 다음 방법을 우선 순위대로 사용하십시오.
- MCP
search_docs도구 (선호 — 관련 스니펫을 직접 반환) - 문서 페이지를 마크다운으로 가져오기 — URL 경로에
.md를 추가하여 모든 문서 페이지를 가져올 수 있습니다. - 웹 검색 — 어떤 페이지를 봐야 할지 모를 때 Supabase 관련 주제 검색
스키마 변경 및 커밋
먼저 프로젝트에서 사용하는 스키마 워크플로를 결정하십시오.
옵션 A: 선언적 스키마
supabase/schemas/가 존재하거나 config.toml에 schema_paths가 설정된 경우 사용합니다. 해당 파일에서 원하는 스키마 상태를 편집한 다음 마이그레이션을 생성하고 검토합니다. 마이그레이션을 직접 작성하는 것으로 시작하지 마십시오. 선언적 데이터베이스 스키마 가이드를 참조하십시오.
옵션 B: 명령형 마이그레이션
프로젝트가 선언적 스키마를 사용하지 않는 경우 사용합니다.
스키마를 변경하려면 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 <descriptive-name> --local --yes - 확인 →
supabase migration list --local
디버깅
Supabase 관련 요청에서 오류가 발생하면(예: Supabase REST API, Postgres 데이터베이스 또는 PostgREST의 오류 코드, 빈 결과, 예기치 않게 RLS에 차단됨, 또는 Auth, Realtime, Edge Functions, Storage와 같은 Supabase 서비스의 오류) 메모리에서 작업하지 말고 진단 또는 수정 제안 전에 Supabase의 모니터링 및 디버깅 문서를 반드시 가져와야 합니다. 동일한 문서는 느린 쿼리 및 누락된 인덱스와 같은 성능 최적화도 다룹니다.
참조 가이드
- 스킬 피드백 → references/skill-feedback.md 반드시 읽어야 할 경우: 사용자가 이 스킬이 잘못된 지침을 제공했거나 정보가 누락되었다고 보고하는 경우.