Supabase로 백엔드를 구성하다 보면 이런 상황이 생깁니다. 로컬에서는 쿼리가 빠른데 데이터가 조금만 쌓이면 느려집니다. RLS(Row-Level Security)를 켰더니 예상치 못한 권한 오류가 납니다. 연결이 갑자기 끊기는데 이유를 모르겠습니다.

Claude Code에 “이 쿼리 최적화해줘”라고 해도 답은 항상 비슷합니다. “인덱스를 추가하세요.” — 어디에, 어떤 컬럼에, 어떤 종류의 인덱스를 왜 추가해야 하는지는 알려주지 않습니다.

supabase-postgres-best-practices 스킬은 이 공백을 메웁니다. Supabase 엔지니어링 팀이 실제 프로덕션 환경에서 축적한 Postgres 운영 노하우를 8개 카테고리로 정리해 에이전트에 직접 주입합니다. 쿼리를 짤 때마다, 스키마를 설계할 때마다, RLS 정책을 작성할 때마다 이 기준이 자동으로 적용됩니다.

상단 히어로 이미지는 PostgreSQL·성능 게이지·보안 실드를 상징하는 3D 미니멀 일러스트로, 본 글의 heroImage 메타데이터와 함께 게시됩니다.

supabase-postgres-best-practices란?

supabase-postgres-best-practices는 Supabase가 공식 배포한 Postgres 성능 최적화 스킬입니다. Supabase의 핵심 인프라가 PostgreSQL 위에서 동작하는 만큼, 이 스킬에 담긴 규칙들은 실제 대규모 서비스 운영 경험을 바탕으로 만들어졌습니다.

주간 설치 수 90,900회로, 데이터베이스를 다루는 개발자들 사이에서 검증된 스킬입니다.

8개 카테고리, 우선순위 기반 규칙들

Supabase는 규칙들을 성능 임팩트 순서로 정리했습니다. 가장 효과가 큰 항목부터 먼저 적용하도록 설계되어 있습니다.

우선순위	카테고리	임팩트	규칙 접두어
1	쿼리 성능 (Query Performance)	CRITICAL	query-
2	연결 관리 (Connection Management)	CRITICAL	conn-
3	보안 & RLS (Security & RLS)	CRITICAL	security-
4	스키마 설계 (Schema Design)	HIGH	schema-
5	동시성 & 잠금 (Concurrency & Locking)	MEDIUM-HIGH	lock-
6	데이터 접근 패턴 (Data Access Patterns)	MEDIUM	data-
7	모니터링 & 진단 (Monitoring & Diagnostics)	LOW-MEDIUM	monitor-
8	고급 기능 (Advanced Features)	LOW	advanced-

쿼리 성능·연결 관리·RLS가 CRITICAL로 분류된 이유는 이 세 가지가 Supabase 환경에서 실제 장애와 보안 사고의 대부분을 차지하기 때문입니다.

이 스킬이 해결하는 문제

설치 방법

# 번들 전체 설치 (supabase와 supabase-postgres-best-practices 포함)
npx skills add supabase/agent-skills

# 이 스킬만 개별 설치
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

npx는 별도 설치 없이 패키지를 바로 실행하는 Node.js 기본 명령어입니다. 위 명령어 한 줄이면 설치가 끝납니다.

실전 데모: RLS 정책 설계

스킬을 설치한 후 Claude Code에서 아래처럼 사용합니다.

# 현재 스키마 파일 검토
/supabase-postgres-best-practices schema.sql

# 마이그레이션 파일 검토
/supabase-postgres-best-practices supabase/migrations/

# 특정 쿼리 성능 검토
/supabase-postgres-best-practices -- "SELECT * FROM posts WHERE user_id = $1"

실제 출력 예시: 스키마 검토

-- 검토 대상 파일: supabase/migrations/20260410_create_posts.sql

CREATE TABLE posts (
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id uuid REFERENCES auth.users(id),
  title text,
  content text,
  created_at timestamptz DEFAULT now()
);
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

검토 완료: supabase/migrations/20260410_create_posts.sql

발견된 문제 (4건):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[security-rls-missing-policy] CRITICAL
  RLS가 활성화됐지만 SELECT, INSERT, UPDATE, DELETE 정책이 하나도 없습니다.
  수정: 최소한 SELECT 정책을 추가하세요.
  
  예시:
  CREATE POLICY "users can view own posts"
    ON posts FOR SELECT
    USING (auth.uid() = user_id);

[query-missing-index] HIGH
  user_id 컬럼이 외래키이지만 인덱스가 없습니다.
  게시물 목록 조회 시 Sequential Scan이 발생합니다.
  수정: CREATE INDEX ON posts (user_id);

[schema-nullable-columns] MEDIUM
  title, content 컬럼에 NOT NULL 제약이 없습니다.
  데이터 무결성 문제가 생길 수 있습니다.
  수정: title text NOT NULL, content text NOT NULL

[schema-soft-delete] LOW
  삭제된 게시물 관리를 위해 deleted_at timestamptz 컬럼 추가를 고려하세요.

규칙 코드(security-rls-missing-policy, query-missing-index)가 명시되므로 어떤 기준으로 문제를 찾았는지 추적할 수 있습니다.

카테고리별 핵심 규칙

1. 쿼리 성능 (CRITICAL)

Supabase 환경에서 가장 빈번하게 발생하는 성능 문제들을 다룹니다.

• 표현식 인덱스: WHERE lower(email) = $1처럼 함수를 사용하는 조건은 일반 인덱스로 최적화되지 않습니다. 표현식 인덱스가 필요합니다.
• N+1 쿼리 탐지: 루프 안에서 개별 쿼리를 반복 호출하는 패턴을 탐지해 JOIN 또는 IN 절로 묶도록 안내합니다.
• Sequential Scan 경고: 큰 테이블에서 인덱스 없이 전체 스캔이 일어나는 패턴을 찾아냅니다.

2. 연결 관리 (CRITICAL)

Supabase는 기본적으로 두 가지 연결 방식을 제공합니다. 잘못 선택하면 연결 한도 초과로 장애가 납니다.

연결 방식	포트	적합한 상황
Direct Connection	5432	마이그레이션, 장기 연결 작업
Supabase Pooler (PgBouncer)	6543	API 서버, 서버리스 함수, 단발성 쿼리

서버리스 환경(Next.js API Routes, Edge Functions)에서 5432를 쓰면 연결이 쌓이면서 데이터베이스가 응답하지 않게 됩니다. 스킬이 이런 패턴을 코드에서 탐지해 경고합니다.

3. 보안 & RLS (CRITICAL)

RLS는 Supabase의 핵심 보안 기능이지만 설정이 복잡합니다.

• 정책 누락 탐지: RLS를 활성화했지만 실제 정책이 없는 테이블을 찾아냅니다.
• SECURITY DEFINER 주의: 함수에 SECURITY DEFINER를 붙이면 RLS를 우회할 수 있습니다. 의도치 않은 사용을 경고합니다.
• auth.uid() 패턴 검증: 인증된 사용자 데이터 격리에 권장되는 패턴이 올바르게 사용됐는지 확인합니다.

4. 스키마 설계 (HIGH)

초기 스키마 설계 실수는 나중에 마이그레이션 비용이 매우 큽니다.

• UUID vs BIGINT: 기본 키 선택 기준과 각각의 트레이드오프
• Soft Delete 패턴: deleted_at 컬럼 활용
• NOT NULL 제약 권장: 데이터 무결성 보장

내부 동작 원리

이 스킬은 references/ 디렉토리에 Supabase의 Postgres 가이드라인 문서를 함께 패키징합니다. 에이전트가 스킬을 실행할 때 이 레퍼런스를 함께 로드해서 규칙 판단에 활용합니다.

허용된 도구 (allowed-tools)

도구	용도
Read	SQL 파일, 마이그레이션 파일, 소스 코드 읽기
Bash	EXPLAIN ANALYZE 실행 등 진단용 쿼리 (선택적)

코드를 자동으로 수정하는 동작은 없습니다. 문제를 찾아서 SQL 수정 예시를 제안하는 역할입니다.

이럴 때 쓰세요 / 이럴 때는 덜 맞아요

잘 맞는 상황	덜 맞는 상황
스키마 설계 초기 단계 검토	MySQL, SQLite 등 다른 DB 환경
Supabase 마이그레이션 파일 PR 리뷰	프론트엔드 UI 코드 검토
RLS 정책 설계 및 검증	성능 프로파일링 (실제 실행 계획 분석 필요)
느린 쿼리 원인 사전 탐지	이미 최적화된 대규모 레거시 DB
서버리스 환경 연결 설정 검토	—

Supabase 공식 번들의 다른 스킬

supabase/agent-skills 번들에는 이 스킬 외에도 하나가 더 있습니다.

• supabase: Postgres, Auth, Edge Functions, Realtime, Storage, Cron, Queue 등 Supabase 전체 제품군을 다루는 포괄적인 개발 가이드 스킬. supabase-postgres-best-practices가 성능·보안에 특화되어 있다면, 이 스킬은 Supabase 생태계 전반의 사용 방법을 안내합니다.

# 번들 전체 설치로 두 스킬 모두 사용
npx skills add supabase/agent-skills

자주 묻는 질문 (FAQ)

Q1: supabase-postgres-best-practices 스킬은 유료인가요?

npx skills add로 설치되는 스킬 자체는 무료 오픈소스입니다. Supabase 프로젝트 유무와 관계없이 사용할 수 있으며, 별도 API 키나 Supabase 계정이 필요하지 않습니다.

Q2: Supabase를 쓰지 않아도 이 스킬이 도움이 되나요?

네, 도움이 됩니다. 이 스킬의 규칙 대부분은 PostgreSQL 일반에 적용되는 베스트 프랙티스입니다. Supabase 특화 규칙(Pooler 연결, auth.uid() 등)은 일부지만, 쿼리 성능·스키마 설계·RLS 패턴은 Supabase 없이도 활용할 수 있습니다.

Q3: Claude Code 외에도 쓸 수 있나요?

네. Cursor, Codex, Gemini CLI, GitHub Copilot 등 npx skills add를 지원하는 모든 AI 에이전트 환경에서 동작합니다. -a 옵션으로 설치 대상 에이전트를 지정하거나, 생략하면 모든 지원 에이전트에 자동 설치됩니다.

Q4: RLS 정책 자동으로 생성해주나요?

자동 생성은 하지 않습니다. 스킬은 문제를 탐지하고 수정 방향을 제안하는 역할만 합니다. 제안된 SQL 예시를 바탕으로 “이 정책 추가해줘”라고 에이전트에게 추가 요청해야 합니다. 이 구조는 의도적입니다 — 보안 정책은 자동 생성보다 검토 후 적용하는 것이 안전합니다.

Q5: vercel-react-best-practices와 함께 써도 되나요?

됩니다. 두 스킬은 역할이 완전히 다릅니다. vercel-react-best-practices는 프론트엔드 React 코드를 담당하고, supabase-postgres-best-practices는 백엔드 데이터베이스 코드를 담당합니다. 풀스택 프로젝트라면 두 스킬을 모두 설치해 프론트엔드와 백엔드를 각각 검토하는 것을 권장합니다.

---