database-query-subagent
Sous-agent spécialisé dans les requêtes base de données — SQL generation, exécution et analyse de résultats. Se déclenche avec "sous-agent DB", "database agent", "SQL agent", "agent base de données", "query agent", "agent qui requête", "text-to-SQL agent", "NL2SQL". Also triggers on "database query agent", "text to SQL subagent".
khalilbenaz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add khalilbenaz/claude-skills-collection --skill database-query-subagent技能说明
name: database-query-subagent description: Sous-agent spécialisé dans les requêtes base de données — SQL generation, exécution et analyse de résultats. Se déclenche avec "sous-agent DB", "database agent", "SQL agent", "agent base de données", "query agent", "agent qui requête", "text-to-SQL agent", "NL2SQL". Also triggers on "database query agent", "text to SQL subagent".
Database Query Sub-Agent
Cas d'usage
Déléguer à ce sous-agent toute interrogation DB depuis un agent parent : NL2SQL (question → SQL), analyse de données complexes, BI assistée par IA, drill-down conversationnel multi-tour. Ne pas utiliser pour des mutations — ce sous-agent est en lecture seule par défaut.
Workflow (10 étapes)
1. Validation des inputs
Recevoir et valider avant toute génération de SQL :
required = ["question", "connection.db_type", "connection.host", "connection.database"]
# Tester la connexion : ping + SELECT 1
# Si échec → retourner immédiatement errors=[{"type": "connection_error", ...}]
Defaults : read_only=True, max_rows=1000, timeout_s=30.
2. Découverte du schéma
Si schema non fourni, l'inférer automatiquement :
-- PostgreSQL / MySQL
SELECT table_name, column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'public'
ORDER BY table_name, ordinal_position;
-- SQLite
SELECT name, sql FROM sqlite_master WHERE type='table';
-- SQL Server
SELECT t.name, c.name, tp.name, c.is_nullable
FROM sys.tables t
JOIN sys.columns c ON t.object_id = c.object_id
JOIN sys.types tp ON c.user_type_id = tp.user_type_id;
Construire un DDL simplifié (max ~2 000 tokens) à injecter dans le prompt de génération.
3. NL → SQL (génération)
Prompt structuré :
Schéma DDL :
<DDL des tables pertinentes uniquement>
Question : <question utilisateur>
Dialecte : <db_type>
Contraintes : lecture seule, LIMIT max_rows
Règles :
- Préférer les CTEs aux sous-requêtes imbriquées
- Alias explicites sur toutes les colonnes ambiguës
- Pas de SELECT * sur tables volumineuses
- Exemples few-shot si disponibles en session_context
Critères de sélection des tables pertinentes : similarité sémantique entre la question et les noms de tables/colonnes (embedding cosine > 0.7, ou matching de mots-clés en fallback).
4. Validation avant exécution
import sqlglot
def validate_query(sql: str, db_type: str, schema: dict, read_only: bool) -> list[str]:
errors = []
# 1. Parse syntaxique
try:
parsed = sqlglot.parse_one(sql, dialect=db_type)
except sqlglot.errors.ParseError as e:
errors.append(f"syntax_error: {e}")
return errors
# 2. Vérifier colonnes et tables vs schéma
for table in parsed.find_all(sqlglot.exp.Table):
if table.name not in schema["tables"]:
errors.append(f"unknown_table: {table.name}")
# 3. Bloquer mutations si read_only
if read_only:
forbidden = (sqlglot.exp.Drop, sqlglot.exp.Delete,
sqlglot.exp.Update, sqlglot.exp.Insert,
sqlglot.exp.Create, sqlglot.exp.AlterTable)
for node in parsed.walk():
if isinstance(node, forbidden):
errors.append(f"mutation_blocked: {type(node).__name__}")
return errors
En cas d'erreur de validation : retourner sans exécuter, inclure la requête invalide dans errors[].query.
5. Exécution sécurisée
from sqlalchemy import create_engine, text
from sqlalchemy.pool import NullPool
engine = create_engine(conn_url, poolclass=NullPool,
connect_args={"connect_timeout": 5})
with engine.connect() as conn:
# Lecture seule au niveau transaction
conn.execute(text("SET TRANSACTION READ ONLY")) # PostgreSQL / MySQL
# SQL Server : utiliser un login sans droits DML
# Timeout
conn.execute(text(f"SET statement_timeout = {timeout_s * 1000}")) # PostgreSQL ms
# LIMIT automatique si absent
if "LIMIT" not in sql.upper() and db_type != "sqlserver":
sql += f" LIMIT {max_rows}"
elif db_type == "sqlserver" and "TOP" not in sql.upper():
sql = sql.replace("SELECT", f"SELECT TOP {max_rows}", 1)
result = conn.execute(text(sql))
rows = [dict(r) for r in result.fetchmany(max_rows + 1)]
truncated = len(rows) > max_rows
return rows[:max_rows], truncated
6. Traitement des résultats
Sérialisation sûre pour JSON :
import math
from decimal import Decimal
from datetime import date, datetime
def serialize_row(row: dict) -> dict:
out = {}
for k, v in row.items():
if v is None:
out[k] = None
elif isinstance(v, (datetime, date)):
out[k] = v.isoformat()
elif isinstance(v, Decimal):
out[k] = float(v)
elif isinstance(v, float) and math.isnan(v):
out[k] = None # NaN non serializable JSON
elif isinstance(v, bytes):
out[k] = v.hex()
else:
out[k] = v
return out
Calculer les stats pour colonnes numériques : {min, max, mean, std, null_count, p25, p50, p75}.
7. Analyse du plan d'exécution
Lancer EXPLAIN si row_count > 10 000 ou execution_time_s > 2 :
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <votre requête>; -- PostgreSQL
EXPLAIN FORMAT=JSON <votre requête>; -- MySQL
Signaux d'alerte à détecter dans le plan :
Seq Scansur table > 100 000 lignes sansWHEREsélectifNested Loopaveccost > 10 000Hash Joinavec spill sur disque ("Disk Spills" > 0)- Cardinalité estimée / réelle ratio > 10× (statistiques obsolètes)
Inclure dans optimization_hints uniquement si gain estimé > 50 %.
8. Dialectes SQL — différences clés
| Feature | PostgreSQL | MySQL | SQLite | SQL Server | BigQuery |
|---|---|---|---|---|---|
| Limite | LIMIT n | LIMIT n | `LIMIT n |