| name | sql-review |
| description | Pre-merge SQL quality gate — lint 26 anti-patterns, grade readability/performance A-F, validate syntax, and scan for injection threats. Use before committing or reviewing SQL changes. |
SQL Review
Requirements
Agent: any (read-only analysis)
Tools used: altimate_core_check, altimate_core_grade, sql_analyze, read, glob, bash (for git operations)
When to Use This Skill
Use when the user wants to:
- Review SQL quality before merging a PR
- Get a quality grade (A-F) on a query or model
- Run a comprehensive lint + safety + syntax check in one pass
- Audit SQL files in a directory for anti-patterns
Do NOT use for:
- Optimizing query performance -> use
query-optimize
- Fixing broken SQL -> use
dbt-troubleshoot
- Translating between dialects -> use
sql-translate
Workflow
1. Collect SQL to Review
Either:
- Read SQL from a file path provided by the user
- Accept SQL directly from the conversation
- Auto-detect changed SQL files from git:
git diff --name-only HEAD~1 | grep '\.sql$'
For dbt models, compile first to get the full SQL:
altimate-dbt compile --model <name>
2. Run Comprehensive Check
Call altimate_core_check — this is the single-call code review that composes:
- Syntax validation: Parse errors with line/column positions
- Lint (26 anti-patterns): SELECT *, unused CTEs, implicit casts, NULL comparisons, missing WHERE on DELETE/UPDATE, cartesian joins, non-sargable predicates, missing partition filters, and more
- Injection scan: Tautology attacks, UNION injection, stacked queries, comment injection, Jinja template injection
- PII exposure: Flags queries accessing columns classified as PII
altimate_core_check(sql: <sql>, schema_context: <schema_object>)
3. Grade the SQL
Call altimate_core_grade to get an A-F quality score with per-category breakdown:
altimate_core_grade(sql: <sql>, schema_context: <schema_object>)
Categories scored:
- Readability: Naming, formatting, CTE structure
- Performance: Anti-patterns, index usage, scan efficiency
- Correctness: NULL handling, join logic, type safety
- Best Practices: Explicit columns, proper materialization hints
4. Run Anti-Pattern Analysis
Call sql_analyze for the detailed anti-pattern breakdown with severity levels and concrete recommendations:
sql_analyze(sql: <sql>, dialect: <dialect>)
5. Present the Review
SQL Review: <file_or_query_name>
==============================
Grade: B+ (82/100)
Readability: A (clear CTEs, good naming)
Performance: B- (missing partition filter on large table)
Correctness: A (proper NULL handling)
Best Practices: C (SELECT * in staging model)
Issues Found: 3
[HIGH] SELECT_STAR — Use explicit column list for contract stability
[MEDIUM] MISSING_PARTITION_FILTER — Add date filter to avoid full scan
[LOW] IMPLICIT_CAST — VARCHAR compared to INTEGER on line 23
Safety: PASS (no injection vectors detected)
PII: PASS (no PII columns exposed)
Verdict: Fix HIGH issues before merging. MEDIUM issues are recommended.
6. Batch Mode
When reviewing multiple files (e.g., all changed SQL in a PR):
- Run the check on each file
- Present a summary table:
| File | Grade | Issues | Safety | Verdict |
|------|-------|--------|--------|---------|
| stg_orders.sql | A | 0 | PASS | Ship |
| int_revenue.sql | B- | 2 | PASS | Fix HIGH |
| mart_daily.sql | C | 5 | WARN | Block |
Usage
/sql-review models/marts/fct_orders.sql -- Review a specific file/sql-review -- Review all SQL files changed in the current git diff/sql-review --all models/ -- Review all SQL files in a directory
