table-studio-plugin

---

name: workflow-base-de-donnees description: Comment lire et modifier la base de données d'un projet en toute sécurité via TableStudio. À utiliser pour toute tâche touchant une base de données réelle : interrogation ou inspection des données, enquête sur un bug de données, correction ou remise à jour de lignes, amorçage, ajout ou modification de tables, colonnes, index ou contraintes, rédaction ou révision d'une migration, ou exécution de SQL. À utiliser aussi chaque fois que vous utiliseriez psql, mysql, sqlite3, wrangler d1 execute, une DATABASE_URL ou un script ponctuel qui ouvre sa propre connexion.

Travailler avec les bases de données via TableStudio

TableStudio est l'application de base de données de l'utilisateur sur son Mac. Ses outils MCP accèdent aux connexions enregistrées sans identifiants, et ils offrent des garde‑fous qu'une session psql brute n'a pas : une exécution à blanc exacte d'une écriture sur les vraies lignes, des copies de test jetables, et une boîte de révision où l'utilisateur approuve les modifications. Utilisez‑les pour le travail sur base de données au lieu de psql, mysql, sqlite3 ou d'un script qui ouvre sa propre connexion.

Les noms d'outils ci‑dessous sont ceux de TableStudio. Votre client peut les afficher avec un préfixe (dans Claude Code : mcp__plugin_tablestudio_tablestudio__list_connections). S'ils sont différés, chargez‑les par ce nom avant le premier appel.

1. Trouver la bonne base de données avant toute action

La note Contexte de base de données de la session, provenant du plugin TableStudio, nomme généralement la connexion TableStudio derrière chaque paramètre de base de données du dépôt, avec son identifiant et son environnement. Utilisez cet identifiant comme connection_id. La note indique également quand les outils de TableStudio ne sont pas disponibles et ce que l'utilisateur doit faire.

Sans la note, ou pour une base de données qu'elle ne nomme pas :

1. Appelez list_connections. Chaque connexion peut contenir ce que l'utilisateur a indiqué à TableStudio à son sujet :
   • project : le projet auquel elle appartient. Préférez les connexions dont le projet correspond au dépôt sur lequel vous travaillez.
   • environment : development, staging ou production. Absent signifie non étiqueté, pas development.
   • read_only : TableStudio refuse les écritures sur celle-ci. staging fonctionne quand même.
   • location : local (ce Mac), remote ou sandbox (une copie jetable, sans risque pour les tests).
   • agent_writes : direct signifie que execute_query peut y écrire (quand les écritures sont activées) ; review signifie que toute modification passe par stage_migration pour que l'utilisateur l'applique. TableStudio décide cela, pas vous : la production, et toute base de données distante que l'utilisateur n'a pas étiquetée development ou staging, sont en review.
   • notes : les notes de l'utilisateur sur les conventions de la base de données (suppressions logicielles, montant en centimes, nommage). Suivez‑les.
2. Faites correspondre d'abord le projet, puis confirmez avec host, port et database par rapport aux paramètres du projet (.env, config).
3. Si deux connexions pourraient être celle que l'utilisateur veut, ou si vous ne pouvez pas déterminer si l'une est la production, demandez. Ne devinez pas.

Ensuite :

• Appelez describe_capabilities une fois avant de planifier quoi que ce soit au‑delà d'une lecture. Il indique si les écritures directes, le staging et les sandbox sont autorisés à ce moment, et nomme le paramètre derrière chacun. Planifiez en fonction plutôt que de découvrir une limite en étant refusé.
• agent_writes: review (production, ou distant sans étiquette) signifie ne jamais écrire directement : préparez les modifications pour révision. TableStudio refuserait de toute façon une écriture directe, alors prévoyez le staging dès le début.
• Vérifiez engine (postgres, mysql, sqlite, d1, clickhouse) avant d'écrire du SQL et écrivez dans ce dialecte.
• Une base de données non enregistrée dans TableStudio ne peut pas être atteinte via ses outils. Demandez à l'utilisateur de l'ajouter dans TableStudio. Ne demandez jamais de mot de passe dans le chat.
• Si un appel échoue parce que la base de données est inaccessible, appelez connection_status. Lorsqu'il indique qu'un serveur local est arrêté, appelez start_local_database avec le instance_id qu'il vous donne.

2. Lecture et investigation

• Recherchez au lieu de deviner les noms : search_schema trouve les tables et colonnes par fragment de nom, et get_table_ddl donne la structure complète, les index, les clés étrangères et referenced_by.
• Exécutez les lectures avec execute_query. Sélectionnez les colonnes dont vous avez besoin, filtrez, agrégez et LIMIT. Les résultats sont limités (max_rows, par défaut 200), donc un résultat truncated n'est pas la réponse complète.
• Les lectures s'exécutent dans une transaction en lecture seule avec une limite de 30 secondes, même en production, donc une lecture ne peut pas modifier les données, même via une fonction. Gardez‑les malgré tout légères : sur une grande table de production, filtrez sur une colonne indexée ou utilisez les estimations de lignes de database_overview au lieu de count(*).
• Un bug de données : reproduisez‑le d'abord dans les données. Trouvez les lignes erronées, comptez‑les, et trouvez quand elles ont commencé (min(created_at)). Ensuite, lisez le code qui les écrit. Montrez à l'utilisateur la requête qui le prouve. Corrigez le code, et si des lignes nécessitent une réparation, c'est une modification de données (section 3).
• Ne collez jamais de secrets, mots de passe ou chaînes de connexion dans du SQL, du code, des documents ou le chat. Le seul endroit où une chaîne de connexion a sa place est le fichier d'environnement gitignoré du projet, pour une base de données locale (la compétence bases‑de‑données‑locales couvre get_connection_url).

3. Modifier les données (INSERT, UPDATE, DELETE)

Sur PostgreSQL :

1. Écrivez l'instruction, puis appelez preflight_statement avec celle‑ci. Vous obtenez un verdict (looks_fine, review ou would_fail), dry_run.rows (exactement combien de lignes cela modifierait, en lecture seule), les cascades vers d'autres tables, et ce qui le ferait échouer.
2. Dites à l'utilisateur ce que cela fera en termes simples : "Cela met à jour 142 lignes dans invoices ; aucune cascade." Si le verdict est would_fail, corrigez d'abord l'instruction. S'il est review, expliquez pourquoi.
3. Ensuite, soit :
   • agent_writes: direct, et les écritures directes sont autorisées : execute_query avec expected_rows défini sur dry_run.rows. Il ne valide que si exactement ce nombre de lignes change, et annule sinon. Sur une base de données PostgreSQL distante, TableStudio refuse une modification de données sans expected_rows.
   • agent_writes: review, écritures non autorisées, ou tout ce que l'utilisateur devrait voir d'abord : stage_migration avec un title clair, le SQL, et une rationale qui inclut le compte de l'exécution à blanc (« Annule les 142 factures en double trouvées par … »). Cela va dans la file d'attente de révision de l'utilisateur dans le Centre Agent de TableStudio et ne s'exécute pas.

Sur les autres moteurs il n'y a pas d'exécution à blanc : exécutez d'abord un SELECT count(*) avec le même WHERE, rapportez le compte, puis suivez la même règle d'exécution ou de mise en révision.

Avant toute action destructive sur une base de données qui compte (un gros DELETE, un DROP, un TRUNCATE), appelez create_restore_point lorsque les sandbox sont activés, et dites à l'utilisateur que vous l'avez fait.

4. Modifier le schéma

Si le dépôt utilise un outil de migration (Prisma, Drizzle, Rails, Django, Alembic, Laravel, Supabase, Knex, Ecto, TypeORM, Wrangler D1, ou des fichiers SQL numérotés simples ; le contexte de session le nomme lorsque le plugin en a détecté un), la modification appartient à cet outil :

1. Effectuez la modification à la manière de l'outil : éditez le schéma et générez une migration, ou écrivez le fichier de migration.
2. Appliquez‑la à la base de données de développement locale avec la commande de développement de l'outil.
3. Vérifiez‑la sur des données réelles (ci‑dessous).
4. Laissez l'application ailleurs au processus de déploiement normal de l'utilisateur. N'exécutez jamais vous‑même la commande de déploiement de l'outil en production.

Exécuter ALTER TABLE directement alors qu'un outil de migration possède le schéma désynchronise l'historique de l'outil avec la base de données, ce qui casse le prochain déploiement.

S'il n'y a pas d'outil de migration, ou si l'utilisateur demande une modification ponctuelle d'une base de données existante :

1. Lisez d'abord la table avec get_table_ddl. Vérifiez referenced_by avant de supprimer ou renommer quoi que ce soit.
2. Essayez sur une copie : create_sandbox (data : none pour le schéma seulement, sample pour un échantillon de lignes réelles), exécutez le DDL sur la connexion du sandbox avec execute_query, et vérifiez qu'il fait ce que vous vouliez.
3. Montrez la différence avec compare_schemas (sandbox comme source_connection_id, la base de données réelle comme target_connection_id).
4. Proposez‑la avec stage_migration sur la connexion réelle. L'utilisateur l'applique depuis TableStudio.

Vérifier une migration sur des données réelles

Une migration qui passe sur la base de données locale peut toujours échouer, ou verrouiller l'application, là où se trouvent les vraies lignes. Avant de considérer une migration comme terminée, vérifiez‑la en lecture seule sur la base de données où elle sera déployée (généralement staging ou production, d'après la note de session ou list_connections) :

1. get_table_ddl pour chaque table qu'elle modifie : combien de lignes, ses index, et ce qui la référence.

2. Pour chaque contrainte qu'elle ajoute, exécutez execute_query avec le SELECT qui trouve les lignes qui la briseraient :

   • NOT NULL : SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE : SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • une clé étrangère : les lignes enfants dont le parent n'existe pas (LEFT JOIN … WHERE parent.id IS NULL)
   • une CHECK, ou un type ou une longueur plus restrictif : les lignes hors du nouveau périmètre

   Des lignes signifient que le déploiement échouerait. Ajoutez une étape de remise à jour ou de nettoyage à la migration, et mentionnez‑le.

3. Sur PostgreSQL, signalez les étapes qui verrouillent ou réécrivent une grande table (voir ci‑dessous) et passez au motif sûr.

4. Lorsque la modification est délicate, exécutez‑la pour de vrai sur une copie : create_sandbox à partir de cette connexion avec data: "sample", execute_query le SQL de la migration sur le sandbox, puis compare_schemas.

Dites à l'utilisateur ce que vous avez vérifié et ce que vous avez trouvé (« orders.status a 0 NULL sur 1.2M lignes, donc SET NOT NULL est sûr »). Tout ceci est en lecture seule : n'appliquez jamais la migration ailleurs que sur la base de données de développement locale.

Verrous sur PostgreSQL

• Construire un index sur une grande table occupée : utilisez CREATE INDEX CONCURRENTLY. Il ne peut pas s'exécuter dans une transaction, donc n'encadrez pas cette instruction avec BEGIN … COMMIT.
• Ajouter une colonne NOT NULL avec une valeur par défaut volatile, changer un type de colonne, ou ajouter une clé étrangère peut réécrire ou verrouiller la table. Mentionnez‑le dans la justification, et envisagez de la diviser en étapes sûres (ajoutez la colonne nullable, remettez à jour par lots, puis SET NOT NULL ; ajoutez une clé étrangère NOT VALID, puis VALIDATE CONSTRAINT).
• schema_issues renvoie du SQL de correction avec un lock_impact pour chaque problème. Lisez‑le avant de proposer une correction.

5. Après avoir mis en révision quelque chose

• Dites à l'utilisateur que cela attend sa révision dans TableStudio et n'a pas été exécuté, et donnez‑lui le review_url du résultat sous forme de lien. Il ouvre la révision avec l'impact de la modification (lignes touchées, verrous, ce qui échouerait), un diagramme du schéma après la modification, et un plan d'annulation. Ne dites jamais qu'une modification mise en révision a été appliquée.
• Si l'utilisateur demande des modifications, list_staged_migrations montre status: changes_requested avec sa note dans review_feedback. Révisez‑la avec update_staged_migration (même migration_id) plutôt que de mettre en révision une deuxième copie, puis dites‑lui qu'elle est prête à être revue à nouveau. Pour la retirer, utilisez remove_staged_migration.
• list_staged_migrations montre également si l'utilisateur l'a appliquée, ignorée ou si elle a échoué.

Lorsque l'utilisateur demande ce qui l'attend (« qu'as‑tu mis en révision ? », « ma migration a‑t‑elle été exécutée ? »), appelez list_staged_migrations pour les connexions de ce dépôt. Rapportez d'abord les en attente, les plus récentes en premier : le titre, la connexion, la date de mise en révision, son review_url, et une ligne sur ce qu'elle fait et son niveau de risque (verrouille‑t‑elle ou réécrit‑elle une grande table, supprime‑t‑elle des données, ou manque‑t‑elle de WHERE ?). Ensuite, celles avec modifications demandées, avec la note de l'utilisateur, et celles qui ont échoué, avec l'erreur. Dites clairement que l'utilisateur applique, renvoie ou ignore ces modifications dans le Centre Agent de TableStudio ; vous ne pouvez pas les appliquer vous‑même.

6. Quand TableStudio dit non

• Un refus qui nomme un paramètre (par exemple, les écritures sont désactivées) est le choix de l'utilisateur. Dites‑lui quel paramètre le permettrait, proposez de mettre la modification en révision à la place, et arrêtez‑vous. Ne contournez pas.
• Si les outils de TableStudio ne sont pas du tout disponibles, la note de session en dit la raison : l'application est fermée, son serveur MCP est éteint (Paramètres → MCP), ou le client n'y est pas encore connecté. Transmettez la correction donnée. Dans Claude Code, l'utilisateur peut se reconnecter avec /mcp une fois TableStudio ouvert.
• Un refus avec blocked: production_review_required ou review_required signifie que cette connexion n'accepte les modifications que par révision : mettez‑les en révision. dry_run_required signifie exécutez d'abord preflight_statement et passez expected_rows. side_effect_function signifie que l'instruction appelle quelque chose qui agit en dehors d'une transaction ; montrez plutôt le SQL à l'utilisateur.
• Le garde‑fou shell du plugin bloque les commandes shell qui écrivent en production. Considérez un blocage comme un signal pour utiliser les étapes ci‑dessus, pas comme quelque chose à contourner.
• Tout ce que vous faites via TableStudio est affiché à l'utilisateur dans son Centre Agent, regroupé par cette conversation.