OpenParable
Skip to content
← Back to skills

SQL Review

Testing & Quality
sql-review

SQL Review is an Agent Skill for testing & quality published in the AltimateAI/altimate-code repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/AltimateAI/altimate-code/blob/HEAD/.opencode/skills/sql-review/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sql-review, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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