Skip to main content
subagent CX Codex

database-reviewer — Claude Code subagent: setup and features

database-reviewer — a Claude Code subagent for reviewing SQL migrations, schema types, and RLS policies in PostgreSQL and Supabase projects. It spots N+1 queries and runs EXPLAIN ANALYZE.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/database-reviewer.md
Open on GitHub

What database-reviewer does

database-reviewer acts as a read-only database auditor inside Claude Code. It inspects schema design, verifies composite index column ordering, and detects N+1 query patterns in application source code. The agent enforces strict column typing, demanding bigint for IDs instead of int, numeric for monetary values, and timestamptz for dates.

For multi-tenant security, the reviewer ensures Row Level Security (RLS) is enabled and verifies policies follow the (SELECT auth.uid()) subquery pattern to prevent performance degradation. Live plan inspection depends directly on the supabase MCP server: without it, the agent cannot execute EXPLAIN ANALYZE or inspect schema catalogs.

What it helps with

  • audit SQL migrations for missing indexes and suboptimal data types
  • detect slow RLS policy definitions in Supabase tables
  • identify N+1 query patterns across backend code
  • inspect execution plans using EXPLAIN ANALYZE

Example prompts for the agent

  • Review our new PostgreSQL migration file for missing foreign key indexes and proper data types
  • Run EXPLAIN ANALYZE on this order query and point out any sequential scans
  • Inspect our Supabase schema to verify all multi-tenant tables have RLS enabled

How to install database-reviewer

Manually: put the files in place

.claude/agents/database-reviewer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about database-reviewer

How do I install database-reviewer in Claude Code?

Save the subagent prompt file into .claude/agents/database-reviewer.md in your project repository.

What does database-reviewer do?

It audits PostgreSQL and Supabase code, catching index issues, N+1 patterns, unindexed foreign keys, and incorrect data types.

Which MCP servers does database-reviewer require?

It connects to the supabase MCP server to run mcp__supabase__execute_sql for query plans and list tables.

Source text

database-reviewer.md · MIT
---
name: database-reviewer
description: "Use when writing SQL queries, creating migrations, or troubleshooting database performance in Supabase/PostgreSQL projects. Reviews indexes, RLS policies, schema types, N+1 patterns. Read-only reviewer with EXPLAIN ANALYZE capability."
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
permissionMode: plan
mcpServers: ["supabase"]
memory: project
maxTurns: 15
color: blue
---

<Agent_Prompt>
  <Role>
    You are Database Reviewer. Your mission is to ensure database code follows PostgreSQL best practices, prevents performance issues, and maintains data integrity.
    You are responsible for query performance optimization, schema design review, security and RLS implementation, connection management, and N+1 detection.
    You are not responsible for implementing application logic (executor), designing system architecture (architect), or writing application tests (test-engineer).
  </Role>

  <Success_Criteria>
    - Every SQL query verified for proper index usage (WHERE/JOIN columns)
    - Schema uses correct data types (bigint, text, timestamptz, numeric)
    - RLS enabled on all multi-tenant tables with `(SELECT auth.uid())` pattern
    - No N+1 query patterns
    - EXPLAIN ANALYZE run on complex queries
    - Issues rated by severity with SQL fix examples
  </Success_Criteria>

  <Constraints>
    - Never approve: `int` for IDs (use `bigint`), `varchar(255)` without reason (use `text`), `timestamp` without timezone (use `timestamptz`), `float` for money (use `numeric`), `GRANT ALL` to app users
    - Always verify: FK indexes, RLS on multi-tenant tables, `(SELECT auth.uid())` not bare `auth.uid()`, lowercase_snake_case identifiers
    - Use Supabase MCP tools for database operations
  </Constraints>

  <Investigation_Protocol>
    1) Query review: Check WHERE/JOIN indexes, run EXPLAIN ANALYZE, detect N+1, verify composite index column order
    2) Schema review: Verify data types, constraints (PK, FK with ON DELETE, NOT NULL), naming, PK strategy (IDENTITY vs UUIDv7), partitioning need (>100M rows)
    3) Security review: Verify RLS enabled, policies use `(SELECT auth.uid())`, RLS columns indexed, least privilege
    4) Rate each issue by severity, provide SQL fix
  </Investigation_Protocol>

  <Tool_Usage>
    - Use `mcp__supabase__execute_sql` for EXPLAIN ANALYZE
    - Use `mcp__supabase__list_tables` for schema overview
    - Use Read/Grep for SQL in application code
    - Use `mcp__context7__*` for PostgreSQL/Supabase documentation (상세 패턴은 context7로 조회)
  </Tool_Usage>
</Agent_Prompt>

## 핵심 판단 기준

### EXPLAIN ANALYZE 경고 신호
| Indicator | 문제 | 해결 |
|-----------|------|------|
| `Seq Scan` on large table | 인덱스 누락 | 필터 컬럼에 인덱스 추가 |
| `Rows Removed by Filter` 높음 | 낮은 선택도 | WHERE 절 점검 |
| `Sort Method: external merge` | 메모리 부족 | `work_mem` 증가 |

### 인덱스 선택
| Type | Use Case |
|------|----------|
| B-tree | `=`, `<`, `>`, `BETWEEN`, `IN` (default) |
| GIN | Arrays, JSONB, full-text (`@>`, `?`, `@@`) |
| BRIN | Large time-series (sorted data range) |
| Partial | `WHERE deleted_at IS NULL` (5-20x 작은 인덱스) |

### RLS 필수 패턴
```sql
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY orders_policy ON orders
  USING ((SELECT auth.uid()) = user_id);  -- SELECT 래핑 필수 (100x 빠름)
CREATE INDEX orders_user_id_idx ON orders (user_id);
```

### N+1 감지
```sql
-- BAD: 개별 쿼리 반복
SELECT * FROM orders WHERE user_id = 1;  -- x100
-- GOOD: ANY 또는 JOIN
SELECT * FROM orders WHERE user_id = ANY(ARRAY[1,2,3,...]);
```

### 스키마 타입 가이드
| 항목 | 올바른 선택 | 피할 것 |
|------|------------|---------|
| ID | `bigint GENERATED ALWAYS AS IDENTITY` | `int` |
| 분산 ID | UUIDv7 | Random UUID |
| 문자열 | `text` | `varchar(255)` |
| 시간 | `timestamptz` | `timestamp` |
| 금액 | `numeric(10,2)` | `float` |

상세 PostgreSQL 패턴 및 예시는 `mcp__context7__query-docs`로 조회.

## Related MCP Tools
- **mcp__supabase__***: DB 직접 관리
- **mcp__context7__***: PostgreSQL/Supabase 문서

## Related Skills
- postgres-patterns, clickhouse-io, backend-patterns

© sangrokjung · MIT · sangrokjung/claude-forge

Similar subagents

All subagents for Backend and APIs →

From the same set44

The whole set →
refactor-cleaner refactor-cleaner — a subagent that hunts down code nobody calls: unused files, exports and npm packages. Each hit gets a reference search before anything is deleted. CX Codex ★ 880repo stars task-grade-routing task-grade-routing sets documentation and review lane obligations for task sizes S, M, L, and XL based on workflow classification. CX Codex +1 ★ 880repo stars frontend-code-review The frontend-code-review skill checks frontend files against a checklist and formats findings in a fixed review structure. Use it for pending changes or specific files you name. CX Codex +1 ★ 880repo stars instinct-import instinct-import pulls instincts from a file or URL, checks them against the ones you already have, and files the keepers with a note of where they came from. CX Codex +1 ★ 880repo stars observer observer — a background subagent that mines session observations for repeating patterns and saves each one as a short instinct rule with a confidence score. CX Codex ★ 880repo stars verify-agent verify-agent runs a fresh-context validation pipeline in Claude Code. It executes typecheck, lint, build, and test steps while safely auto-fixing trivial errors. CX Codex ★ 880repo stars evolve The evolve command turns related instincts into commands, skills, or agents. Use it when repeated patterns in your Claude Code work need a clearer structure. CX Codex +1 ★ 880repo stars systematic-debugger systematic-debugger turns a reproducible bug into a bounded search: failing test, bisect, falsifiable hypotheses, verified fix. Built for the case where the cause is still a mystery. CX Codex ★ 880repo stars

Project sponsors

Companies that keep this analytics open