sql-optimization-patterns

Vue d’ensemble de la skill sql-optimization-patterns

Ce que fait sql-optimization-patterns

La skill sql-optimization-patterns aide un agent à diagnostiquer un SQL lent, à expliquer pourquoi une requête est lente et à proposer des correctifs concrets autour de la structure de la requête, de l’indexation, des jointures, de la pagination et de la lecture des plans d’exécution. Elle est surtout utile lorsque vous faites face à un vrai problème de performance et que vous voulez un workflow d’optimisation structuré, plutôt que des conseils génériques du type « ajoutez un index ».

Pour qui l’installer

Cette skill convient aux ingénieurs backend, ingénieurs base de données, équipes plateforme et développeurs applicatifs qui ont besoin d’accélérer des requêtes sans avancer à l’aveugle. Elle est particulièrement pertinente pour les équipes qui travaillent avec des sorties EXPLAIN de type PostgreSQL, mais les schémas de raisonnement restent transposables à d’autres bases relationnelles.

Le vrai besoin métier auquel elle répond

Les utilisateurs ont généralement besoin de plus qu’une simple relecture de syntaxe. Ils doivent :

• identifier pourquoi une requête est lente
• relier les symptômes du plan aux causes racines probables
• choisir entre une réécriture de requête et des changements d’index
• éviter les « correctifs » qui accélèrent une requête mais dégradent les écritures ou le stockage
• communiquer clairement les arbitrages à une équipe

C’est là que sql-optimization-patterns apporte plus de valeur qu’un simple prompt.

Ce qui différencie cette skill

Son principal point fort est son approche orientée patterns. Elle ne se contente pas de dire « optimiser SQL » ; elle pousse l’agent vers des préoccupations concrètes d’ingénierie base de données, comme :

• la lecture de EXPLAIN et EXPLAIN ANALYZE
• la détection des scans séquentiels, des mauvais choix de jointure et d’une pagination inefficace
• le choix réfléchi des stratégies d’indexation
• la prise en charge d’anti-patterns fréquents comme les accès N+1

Cas où elle est la plus adaptée — et moins adaptée

Meilleur fit :

• une requête lente déjà identifiée
• un plan de requête que vous pouvez coller tel quel
• des détails de schéma, d’index et de volumétrie disponibles
• un travail de performance lié à la latence API ou à la charge base de données

Moins adaptée :

• aucun texte de requête
• aucun plan d’exécution
• des questions purement architecturales au niveau ORM sans visibilité SQL
• du tuning spécifique à un moteur qui dépend d’internals non fournis dans le prompt

Comment utiliser la skill sql-optimization-patterns

Contexte d’installation pour sql-optimization-patterns

Le dépôt ne met pas en avant d’installeur personnalisé dans SKILL.md. Il faut donc l’installer via votre workflow habituel de chargement de skills pour le dépôt wshobson/agents, puis vérifier que votre agent peut accéder à la skill nommée sql-optimization-patterns.

Si votre environnement utilise le flux Skills classique, le schéma pratique consiste à ajouter le dépôt, puis à invoquer la skill par son nom dans une tâche qui demande explicitement une analyse d’optimisation SQL.

Commencez par lire ce fichier

Commencez par :

• plugins/developer-essentials/skills/sql-optimization-patterns/SKILL.md

Cette skill est autonome. Il n’y a ni references/, ni rules/, ni scripts de support dans le dossier de la skill ; l’essentiel des consignes utiles se trouve donc dans ce fichier unique. C’est un avantage pour une adoption rapide, mais cela signifie aussi que la qualité de vos entrées compte davantage.

Les entrées nécessaires à la skill

Pour obtenir une réponse solide, fournissez à l’agent :

• la requête SQL
• le moteur de base de données et sa version si vous les connaissez
• les schémas de tables ou les colonnes pertinentes
• les index existants
• l’ordre de grandeur du nombre de lignes ou la taille approximative des tables
• la sortie EXPLAIN ou EXPLAIN ANALYZE
• l’objectif métier, par exemple « réduire la latence P95 d’un endpoint »

Sans données de plan, l’agent peut encore suggérer des patterns, mais les conseils seront moins fiables.

Prompt minimum viable

Un prompt sql-optimization-patterns usage exploitable ressemble à ceci :

Use the sql-optimization-patterns skill.

Database: PostgreSQL 15
Goal: reduce this query from 2.4s to under 200ms
Tables:
- users(id, email, created_at, status)
- orders(id, user_id, order_total, created_at)

Current indexes:
- users_pkey(id)
- orders_user_id_idx(user_id)

Query:
SELECT u.*, o.order_total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at > NOW() - INTERVAL '30 days'
ORDER BY u.created_at DESC
LIMIT 100;

EXPLAIN ANALYZE:
[paste full plan]

Please identify likely bottlenecks, explain the plan, recommend query/index changes, and rank fixes by expected impact and risk.

Comment transformer une demande floue en demande robuste

Demande faible :

Make this SQL faster.

Demande robuste :

Use sql-optimization-patterns for Database Engineering.

I need:
1. plan interpretation
2. likely root cause
3. index recommendations with rationale
4. query rewrite options
5. tradeoffs for write amplification and storage
6. a safe rollout order

Engine: PostgreSQL 14
Traffic pattern: read-heavy API endpoint
Data scale: users 8M rows, orders 120M rows
Current problem: endpoint P95 is 1.8s, DB CPU spikes during peak
Query: [paste]
Plan: [paste]
Existing indexes: [paste]

Le deuxième prompt fonctionne mieux, car il donne à la skill suffisamment de contexte opérationnel pour prioriser les correctifs au lieu d’aligner des conseils génériques.

Workflow pratique pour obtenir les meilleurs résultats

Un bon workflow consiste à :

1. coller la requête exacte et le plan complet
2. demander à l’agent d’expliquer en langage clair les principaux postes de coût
3. demander 2 à 3 correctifs possibles, pas 10
4. demander les avantages et inconvénients attendus pour chacun
5. implémenter d’abord le changement le moins risqué
6. relancer EXPLAIN ANALYZE
7. comparer l’avant et l’après

Cette approche garde la skill ancrée dans des résultats mesurables, plutôt que dans du tuning spéculatif.

Ce que la skill fait particulièrement bien

Le contenu source met fortement l’accent sur :

• l’interprétation de EXPLAIN
• la stratégie d’indexation
• l’analyse des patterns de jointure
• l’efficacité de la pagination
• les problèmes de requêtes N+1

Autrement dit, c’est une très bonne option pour l’optimisation au niveau requête et les décisions de schéma/index, pas seulement pour reformater du SQL.

Ce qu’il faut demander explicitement

Pour obtenir des résultats plus utiles lors de l’installation de sql-optimization-patterns install et de son utilisation, demandez à l’agent :

• « quel est le principal goulot d’étranglement dans ce plan »
• « s’il vaut mieux commencer par un nouvel index ou une réécriture de la requête »
• « quels types de scan/jointure me pénalisent »
• « si la requête peut devenir index-only »
• « comment ce changement affecte les écritures, le vacuum ou le stockage »
• « quoi mesurer après le déploiement »

Ces formulations obligent à prioriser, ce qui fait souvent la différence entre une réponse utile et une réponse bruitée.

Freins courants à l’adoption

Les principaux freins ne viennent généralement pas de l’installation, mais du manque d’éléments factuels :

• sortie de plan incomplète
• aucune information sur la taille des tables
• aucun index actuel listé
• SQL généré par un ORM collé sans contexte métier
• demande de « bonnes pratiques » au lieu de diagnostiquer un cas réel

Si vous ne fournissez que le texte de la requête, attendez-vous à des suggestions larges. Si vous ajoutez le plan, le schéma et le contexte de charge, la skill devient nettement plus utile pour prendre des décisions.

Interpréter la sortie sans prendre de risques

Ne considérez pas chaque index proposé comme un gain gratuit. Une bonne approche sql-optimization-patterns guide consiste à vérifier :

• si les prédicats de filtre ou de jointure correspondent réellement à l’ordre d’index proposé
• si la requête est suffisamment sélective pour en tirer parti
• si un index composite est préférable à plusieurs index mono-colonne
• si le correctif aide une requête mais dégrade les performances d’insertion ou de mise à jour

La skill est la plus efficace lorsqu’elle sert à formuler des hypothèses que vous pouvez tester immédiatement.

FAQ sur la skill sql-optimization-patterns

sql-optimization-patterns vaut-elle la peine d’être installée si je connais déjà SQL ?

Oui, si vous voulez une analyse d’optimisation cohérente sous pression. La valeur n’est pas dans les bases de SQL ; elle réside dans l’ensemble structuré de patterns autour des plans, des types de scan, des jointures et des choix d’index.

Cette skill est-elle adaptée aux débutants ?

Plutôt oui, mais les débutants devraient l’utiliser sur des exemples réels. La skill devient beaucoup plus claire quand vous comparez le texte de la requête à la sortie EXPLAIN ANALYZE. Si vous débutez avec les plans d’exécution, demandez d’abord à l’agent de définir chaque nœud important en langage simple avant de recommander des changements.

En quoi est-ce meilleur qu’un prompt IA classique ?

Un prompt classique donne souvent des conseils de tuning génériques. La sql-optimization-patterns skill est pensée pour un workflow d’optimisation reproductible et centrée sur les signaux qui comptent vraiment en ingénierie base de données, en particulier l’interprétation des plans et la stratégie d’indexation.

Faut-il obligatoirement PostgreSQL ?

Non, mais les exemples ont clairement une coloration PostgreSQL. Si vous utilisez MySQL, SQLite, SQL Server ou un autre moteur, indiquez le nom du moteur et l’équivalent de sortie de plan pour que l’agent adapte ses recommandations.

Quand ne faut-il pas utiliser sql-optimization-patterns ?

Ne commencez pas par cette skill si le problème principal concerne :

• le connection pooling
• la contention sur les verrous sans preuve côté requête
• une saturation d’infrastructure en dehors de la base de données
• l’absence de stratégie de cache applicatif
• un mauvais usage de l’ORM qui masque le SQL réel

Dans ces cas-là, cette skill pourra peut-être aider plus tard, mais ce n’est pas le premier outil à sortir.

Peut-elle aider sur la conception de schéma, pas seulement sur une requête lente ?

Oui. La skill couvre la stratégie d’indexation et les patterns de requête qui passent à l’échelle, donc elle peut aussi appuyer des décisions de schéma. Elle reste néanmoins la plus efficace lorsqu’elle est reliée à des patterns d’accès, des filtres attendus, des jointures, des ordres de tri et des volumes de données.

Comment améliorer la skill sql-optimization-patterns

Donner à sql-optimization-patterns de meilleurs éléments de preuve

Le moyen le plus rapide d’améliorer les résultats est de fournir :

• le texte complet de la requête, pas une reformulation
• la sortie complète du plan, pas seulement les premières lignes
• le timing réel de EXPLAIN ANALYZE lorsque c’est sans risque
• les index existants
• la cardinalité approximative et les nombres de lignes
• si la charge est majoritairement en lecture ou en écriture

De meilleurs éléments produisent des recommandations plus crédibles et moins d’index hors sujet.

Demander des recommandations classées

La skill est plus utile si vous lui demandez de classer les correctifs selon :

• l’impact attendu sur la latence
• l’effort d’implémentation
• le risque opérationnel
• le surcoût en écriture
• la réversibilité

Ce classement aide les équipes à choisir une action, pas seulement à accumuler des idées.

Forcer l’analyse des arbitrages

Un mode d’échec fréquent consiste à accepter une solution très rapide en lecture qui rend les écritures coûteuses ou gonfle les index. Pour améliorer la sortie de sql-optimization-patterns, demandez :

• « Quel est le coût de cet index sur les insertions et les mises à jour ? »
• « Cela va-t-il créer des index redondants ? »
• « Le partitionnement ou une réécriture seraient-ils préférables à un index de plus ? »
• « La keyset pagination est-elle préférable ici à une offset pagination ? »

Utiliser une itération avant/après

Après la première recommandation, relancez le plan et demandez à la skill de comparer :

• le goulot d’étranglement initial
• le nouveau goulot d’étranglement
• ce qui s’est amélioré
• ce qui reste coûteux
• si l’optimisation suivante vaut encore la peine d’être faite

C’est la manière la plus fiable de transformer la skill en boucle d’optimisation, plutôt qu’en réponse ponctuelle.

Surveiller les modes d’échec fréquents

Les erreurs les plus courantes sont :

• optimiser sans données ANALYZE
• ajouter des index pour des filtres peu sélectifs
• ignorer l’ordre des jointures et les estimations de cardinalité
• réécrire le SQL sans valider le nouveau plan
• se focaliser sur une requête en passant à côté d’un pattern N+1 en amont

Vous pouvez réduire ces erreurs en demandant à l’agent d’énoncer explicitement ses hypothèses avant de proposer des changements.

Des patterns de prompt qui améliorent la qualité des réponses

Utilisez des prompts comme :

Use the sql-optimization-patterns skill and do not give generic advice.
Base recommendations on the query plan provided.
For each proposed fix, explain:
1. why it should help
2. what plan node it targets
3. what tradeoff it introduces
4. how to validate it after deployment

Ce format pousse l’agent à relier chaque suggestion à des éléments concrets.

Améliorer l’adoption dans l’équipe

Si vous voulez que cette skill aide une équipe, standardisez le modèle d’entrée :

• moteur/version
• requête
• schéma
• index
• plan
• tailles de tables
• latence cible
• notes sur la charge

Cela réduit la variabilité et rend sql-optimization-patterns for Database Engineering beaucoup plus reproductible d’un incident à l’autre et d’une revue de code à l’autre.