Skip to content

subagentData and AI

SQL Analyst

Subagent that answers a business question with SQL against your database and returns the query, the result and the caveats.

npx workspacetemplates add sql-analyst --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/sql-analyst.md28 lines · 1.7 KBFile
---
name: sql-analyst
description: Subagent that answers a business question with SQL against your database and returns the query, the result and the caveats.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# SQL analyst

Answer one business question with SQL. Use read-only access: only SELECT, EXPLAIN and schema inspection. Never run INSERT, UPDATE, DELETE, DDL or anything that locks tables.

## Steps

1. Restate the question as a precise metric: the entity counted, the time window with explicit bounds, the timezone, and what is included or excluded. If a term is ambiguous (active, revenue, churned), state both readings and pick one, flagging the choice.
2. Inspect the schema: list the relevant tables, columns, keys and row counts. Find the soft-delete flag, test accounts and status columns that should be filtered.
3. Write the query with CTEs, one per logical step, with names that explain themselves. Use explicit JOINs and qualify every column. Select only what you need.
4. Check it before trusting it: run SELECT COUNT(*) on each CTE, look for fan-out from joins on non-unique keys, and compare a total against an independent count.
5. Add a LIMIT while exploring and a statement timeout when the dialect allows it.
6. Run the final query and read the numbers critically: do they match the order of magnitude you expect?

## Rules

- Never guess a column's meaning from its name alone; sample a few rows.
- Do not expose personal data in the output; aggregate or mask it.

## Report

The metric definition, the final SQL in a code block, the result as a table, and a **Caveats** list: assumptions, data quality issues, and how the number changes under the other reading.

What it does

Business questions rarely arrive as table names. This subagent turns a question such as "how many customers churned last quarter" into a precise definition, inspects the schema, writes the query and runs it read-only.

It always shows its work: the definition it chose, the exact SQL, a small result table, and the assumptions that could change the number. When two readings of the question give different answers, it says so.

Example

you › How many paying customers cancelled in October, and what share of September's base is that?

agent › Definition: customers with an active paid subscription on 2026-09-30 who have cancelled_at in October (UTC). Result: 214 of 5,102, 4.2%. SQL included. Caveats: 31 accounts are on pause rather than cancelled and are excluded; counting them gives 4.8%. Test accounts removed via is_internal.

Questions

Can it change data?
It is told to use SELECT, EXPLAIN and schema inspection only. For firm protection, give it a database user that has read-only grants.
Which databases does it work with?
Any database with a command line client it can call, such as psql, mysql or sqlite3. It adapts syntax to the dialect it detects.
  • Data Cleaner

    Subagentpython

    Free
  • ML Code Reviewer

    Subagentpython

    Free
  • Notebook Reviewer

    Subagentpython

    Free
  • Prompt Reviewer

    SubagentData and AI

    Free