Infrastructure/eqs-platform

Fork 0

`pnpm --filter api db:dev` est interactif : il bloque tout appelant non interactif, et l'interrompre laisse un verrou consultatif Postgres qui exige un `pg_terminate_backend` manuel #63

New issue

Closed

opened 2026-09-12 16:32:12 +00:00 by nicolas-fryder · 2 comments

nicolas-fryder commented

2026-09-12 16:32:12 +00:00

Owner

Ce qui ne va pas

AGENTS.md du template documente la commande de migration sans dire qu'elle est interactive :

pnpm --filter api db:dev — une migration après un changement de schéma. Elle réécrit prisma/migrations/migration_lock.toml à chaque fois : ce fichier appartient à Prisma, on le laisse tel qu'il l'écrit et on n'y ajoute rien (#11).

Elle mappe sur prisma migrate dev, qui demande un nom de migration au clavier quand --name est absent. Un appelant non interactif — un agent de codage, un script, une session sans TTY — se retrouve bloqué sur une invite qu'il ne peut ni voir ni satisfaire. Il n'y a aucune forme non interactive documentée : il faut deviner --name, ce qui est exactement le « montage qu'il a fallu deviner » que le dépôt demande de signaler.

Et le mode de sortie est pire que le blocage. Interrompre le processus resté en attente de l'invite laisse le verrou consultatif Postgres de Prisma pris. Toute migration suivante attend indéfiniment ce verrou, sans message expliquant ce qu'elle attend. Il faut alors aller terminer la session côté base à la main :

select pg_terminate_backend(pid) from pg_stat_activity where ...;

C'est une opération que personne ne devine à partir du symptôme observé (« la migration ne rend pas la main »), et qui suppose de savoir que Prisma prend un verrou consultatif.

Reproduction

Dans un clone du template, base de développement levée :

# 1. changer quelque chose dans prisma/schema/*.prisma
pnpm --filter api db:dev < /dev/null

Obtenu : la commande attend un nom de migration et ne rend pas la main. Avec un stdin fermé, elle ne peut pas aboutir.

Puis, après interruption :

pnpm --filter api db:dev --name quelque_chose

Obtenu : attente indéfinie sur le verrou consultatif laissé par le processus précédent, sans indication de ce qui est attendu.

Attendu, dans les deux cas : soit une forme non interactive documentée, soit un message qui nomme l'invite et dit comment la contourner — et, sur le second, un message qui dise quel verrou est attendu et comment le lever.

Ce que ça coûte

Bloquant pour tout usage automatisé, et coûteux même en usage humain à cause du second effet.

Le contexte de ce constat rend la chose structurelle plutôt qu'anecdotique : je construis, dans un satellite, un système où des agents écrivent du code et jouent les commandes du socle sans personne devant l'écran. La chaîne de vérification du socle est précisément ce qui rend ce système possible — mais une commande documentée qui attend une frappe au clavier la rend inutilisable telle quelle, et le AGENTS.md que l'agent lit ne l'avertit pas.

Plus largement : AGENTS.md est le document écrit pour des agents. Une commande qu'il recommande sans dire qu'elle est interactive est un piège posé à son lecteur principal.

Le coût mesuré ici : un agent bloqué, puis un verrou à lever à la main dans la base, puis la migration rejouée. Une dizaine de minutes pour quelqu'un qui comprend ce qui se passe ; un mur pour quelqu'un qui ne le comprend pas.

Ce que je proposerais

Documenter la forme non interactive dans AGENTS.md, puisque c'est le document que les agents lisent : pnpm --filter api db:dev --name <nom_en_snake_case>, en disant que sans --name la commande attend une saisie.
Ou mieux, rendre le script non interactif par construction : que db:dev exige son nom en argument et échoue en le réclamant, plutôt que d'attendre. Un échec qui nomme ce qui manque vaut mieux qu'une attente muette — c'est déjà la doctrine du socle au démarrage d'une application (plateforme.ts), elle s'applique aussi bien ici.
Documenter le verrou consultatif : une ligne dans le guide disant qu'une migration interrompue laisse un verrou, et la requête pour le lever. Le symptôme (« ça ne rend pas la main ») ne mène pas à la cause.
Éventuellement, un contrôle ou une note d'audit qui signale les scripts du template susceptibles d'attendre une saisie — c'est une propriété qui se vérifie mécaniquement (stdin fermé, code de sortie), et qui vaut pour plus d'une commande.

Versions

@eqs/cli, @eqs/tooling, @eqs/testing : ^0.8.1.
prisma / @prisma/client : ^6.16.1.
Clone neuf, profil nest, PostgreSQL 18, constaté le 2026-09-12 sur Windows 11 / Docker Desktop.

Contournement

Migration rejouée avec --name explicite, après avoir levé le verrou par pg_terminate_backend. Aucun contournement ne subsiste dans le dépôt — mais il subsiste dans les habitudes : tout appelant automatisé de ce dépôt doit désormais savoir qu'il faut passer --name, et ça n'est écrit nulle part dans le socle. C'est ce que ce ticket demande de corriger.

## Ce qui ne va pas `AGENTS.md` du template documente la commande de migration sans dire qu'elle est interactive : > `pnpm --filter api db:dev` — une migration après un changement de schéma. Elle réécrit `prisma/migrations/migration_lock.toml` à chaque fois : ce fichier appartient à Prisma, on le laisse tel qu'il l'écrit et on n'y ajoute rien (#11). Elle mappe sur `prisma migrate dev`, qui **demande un nom de migration au clavier** quand `--name` est absent. Un appelant non interactif — un agent de codage, un script, une session sans TTY — se retrouve bloqué sur une invite qu'il ne peut ni voir ni satisfaire. Il n'y a aucune forme non interactive documentée : il faut **deviner** `--name`, ce qui est exactement le « montage qu'il a fallu deviner » que le dépôt demande de signaler. Et le mode de sortie est pire que le blocage. Interrompre le processus resté en attente de l'invite laisse **le verrou consultatif Postgres de Prisma pris**. Toute migration suivante attend indéfiniment ce verrou, sans message expliquant ce qu'elle attend. Il faut alors aller terminer la session côté base à la main : ```sql select pg_terminate_backend(pid) from pg_stat_activity where ...; ``` C'est une opération que personne ne devine à partir du symptôme observé (« la migration ne rend pas la main »), et qui suppose de savoir que Prisma prend un verrou consultatif. ## Reproduction Dans un clone du template, base de développement levée : ```bash # 1. changer quelque chose dans prisma/schema/*.prisma pnpm --filter api db:dev < /dev/null ``` Obtenu : la commande attend un nom de migration et ne rend pas la main. Avec un stdin fermé, elle ne peut pas aboutir. Puis, après interruption : ```bash pnpm --filter api db:dev --name quelque_chose ``` Obtenu : attente indéfinie sur le verrou consultatif laissé par le processus précédent, sans indication de ce qui est attendu. Attendu, dans les deux cas : soit une forme non interactive documentée, soit un message qui nomme l'invite et dit comment la contourner — et, sur le second, un message qui dise **quel verrou** est attendu et **comment** le lever. ## Ce que ça coûte Bloquant pour tout usage automatisé, et coûteux même en usage humain à cause du second effet. Le contexte de ce constat rend la chose structurelle plutôt qu'anecdotique : je construis, dans un satellite, un système où des agents écrivent du code et jouent les commandes du socle sans personne devant l'écran. La chaîne de vérification du socle est précisément ce qui rend ce système possible — mais une commande documentée qui attend une frappe au clavier la rend inutilisable telle quelle, et le `AGENTS.md` que l'agent lit ne l'avertit pas. Plus largement : `AGENTS.md` est le document écrit **pour des agents**. Une commande qu'il recommande sans dire qu'elle est interactive est un piège posé à son lecteur principal. Le coût mesuré ici : un agent bloqué, puis un verrou à lever à la main dans la base, puis la migration rejouée. Une dizaine de minutes pour quelqu'un qui comprend ce qui se passe ; un mur pour quelqu'un qui ne le comprend pas. ## Ce que je proposerais 1. **Documenter la forme non interactive dans `AGENTS.md`**, puisque c'est le document que les agents lisent : `pnpm --filter api db:dev --name <nom_en_snake_case>`, en disant que sans `--name` la commande attend une saisie. 2. **Ou mieux, rendre le script non interactif par construction** : que `db:dev` exige son nom en argument et échoue en le réclamant, plutôt que d'attendre. Un échec qui nomme ce qui manque vaut mieux qu'une attente muette — c'est déjà la doctrine du socle au démarrage d'une application (`plateforme.ts`), elle s'applique aussi bien ici. 3. **Documenter le verrou consultatif** : une ligne dans le guide disant qu'une migration interrompue laisse un verrou, et la requête pour le lever. Le symptôme (« ça ne rend pas la main ») ne mène pas à la cause. 4. Éventuellement, un contrôle ou une note d'audit qui signale les scripts du template susceptibles d'attendre une saisie — c'est une propriété qui se vérifie mécaniquement (stdin fermé, code de sortie), et qui vaut pour plus d'une commande. ## Versions - `@eqs/cli`, `@eqs/tooling`, `@eqs/testing` : `^0.8.1`. - `prisma` / `@prisma/client` : `^6.16.1`. - Clone neuf, profil `nest`, PostgreSQL 18, constaté le 2026-09-12 sur Windows 11 / Docker Desktop. ## Contournement Migration rejouée avec `--name` explicite, après avoir levé le verrou par `pg_terminate_backend`. Aucun contournement ne subsiste dans le dépôt — mais il subsiste dans les **habitudes** : tout appelant automatisé de ce dépôt doit désormais savoir qu'il faut passer `--name`, et ça n'est écrit nulle part dans le socle. C'est ce que ce ticket demande de corriger.

nicolas-fryder referenced this issue

2026-09-12 16:46:00 +00:00

refuser-genere.mjs refuse tout prisma/migrations/**, y compris un squelette --create-only jamais appliqué : aucune DDL sur-mesure (trigger, fonction, vue, contrainte) n'est possible par la voie documentée #64

nicolas-fryder commented

2026-09-12 16:46:27 +00:00

Author

Owner

Vrai, et votre phrase de conclusion est la meilleure raison de le corriger :

AGENTS.md est le document écrit pour des agents. Une commande qu'il recommande sans dire qu'elle est interactive est un piège posé à son lecteur principal.

J'ai pris votre option 2 plutôt que la 1, pour la raison que vous donnez vous-même : « un échec qui nomme ce qui manque vaut mieux qu'une attente muette — c'est déjà la doctrine du socle au démarrage d'une application ». Documenter aurait laissé le piège en place pour qui ne lit pas.

`db:dev` refuse au lieu d'attendre

$ pnpm --filter api db:dev
Il manque `--name`.

  pnpm --filter api db:dev --name ajout_colonne_statut

Sans lui, `prisma migrate dev` attend un nom au CLAVIER. Un appelant non
interactif reste bloqué — et l'interrompre laisse le verrou consultatif de
Prisma pris, ce qui fait attendre toutes les migrations suivantes sans le
dire. Voir « Le verrou d'une migration interrompue » dans AGENTS.md.

Pour une DDL que le schéma ne sait pas exprimer (déclencheur, vue,
contrainte), ajoutez `--create-only` : le squelette produit s'édite.

Sortie 1, immédiate, stdin fermé. Le message porte les deux conséquences que vous décrivez, pas seulement la première : l'attente, et ce qu'une interruption laisse derrière.

Le script lance le point d'entrée JS de Prisma avec le Node courant, jamais le shim .cmd — passer par un shell ramènerait cmd.exe, qui a déjà coûté deux tickets à ce dépôt (#22, #24).

Votre option 3 : le verrou

C'est la partie que je trouve la plus utile de votre ticket, parce que personne ne remonte du symptôme à la cause. AGENTS.md a maintenant sa section :

Prisma prend un verrou consultatif sur la base pendant migrate dev. Interrompre la commande le laisse pris, et la migration suivante attend indéfiniment sans dire ce qu'elle attend. Le symptôme est « ça ne rend pas la main » ; la cause n'est devinable par personne.

avec la requête pg_terminate_backend. Et une phrase qui dit pourquoi la section survit à la correction : la commande n'est plus interactive, mais un Ctrl+C au mauvais moment produit le même état.

Votre option 4, et ce que je n'ai pas fait

un contrôle qui signale les scripts du template susceptibles d'attendre une saisie — c'est une propriété qui se vérifie mécaniquement (stdin fermé, code de sortie)

Elle est bonne, et je ne l'ai pas prise — pour une raison que je préfère écrire que taire. Vérifier « ce script attend-il une saisie » demande de jouer chaque script avec stdin fermé. Or les scripts d'un satellite montent des bases, appellent des registres, déploient. Un contrôle qui les lance tous pour voir lesquels bloquent est un contrôle qui fait des dégâts en cherchant.

Il y aurait une forme statique — chercher les commandes connues pour être interactives (prisma migrate dev sans --name, gh sans --yes, npm login) — mais c'est une liste à tenir, et vous connaissez déjà mon avis sur les listes à tenir : le prochain outil interactif repassera par la même case.

Si vous voyez une troisième voie, elle m'intéresse. En attendant, la correction structurelle vaut pour ce script-ci, et la remarque est consignée.

Ce que je n'ai pas vérifié moi-même

Je n'ai pas rejoué l'invite ni le verrou : la base de développement du gabarit n'est pas levée sur ce poste, et la monter pour reproduire une interruption de migration coûtait plus que ça ne prouvait. Je me suis appuyé sur votre mesure et sur le comportement documenté de Prisma. Ce que j'ai vérifié, c'est le refus : sortie 1, message complet, stdin fermé.

Branche fix/migrations-et-db-dev sur le gabarit — elle porte aussi #64. Fusionnable tout de suite.

Vrai, et votre phrase de conclusion est la meilleure raison de le corriger : > `AGENTS.md` est le document écrit **pour des agents**. Une commande qu'il recommande sans dire qu'elle est interactive est un piège posé à son lecteur principal. J'ai pris votre option 2 plutôt que la 1, pour la raison que vous donnez vous-même : « un échec qui nomme ce qui manque vaut mieux qu'une attente muette — c'est déjà la doctrine du socle au démarrage d'une application ». Documenter aurait laissé le piège en place pour qui ne lit pas. ## `db:dev` refuse au lieu d'attendre ``` $ pnpm --filter api db:dev Il manque `--name`. pnpm --filter api db:dev --name ajout_colonne_statut Sans lui, `prisma migrate dev` attend un nom au CLAVIER. Un appelant non interactif reste bloqué — et l'interrompre laisse le verrou consultatif de Prisma pris, ce qui fait attendre toutes les migrations suivantes sans le dire. Voir « Le verrou d'une migration interrompue » dans AGENTS.md. Pour une DDL que le schéma ne sait pas exprimer (déclencheur, vue, contrainte), ajoutez `--create-only` : le squelette produit s'édite. ``` Sortie 1, immédiate, stdin fermé. Le message porte les **deux** conséquences que vous décrivez, pas seulement la première : l'attente, et ce qu'une interruption laisse derrière. Le script lance le point d'entrée JS de Prisma avec le Node courant, jamais le shim `.cmd` — passer par un shell ramènerait `cmd.exe`, qui a déjà coûté deux tickets à ce dépôt ([#22](https://git.equilibre-structures.fr/Infrastructure/eqs-satellite-template/issues/22), [#24](https://git.equilibre-structures.fr/Infrastructure/eqs-satellite-template/issues/24)). ## Votre option 3 : le verrou C'est la partie que je trouve la plus utile de votre ticket, parce que personne ne remonte du symptôme à la cause. `AGENTS.md` a maintenant sa section : > Prisma prend un **verrou consultatif** sur la base pendant `migrate dev`. Interrompre la commande le laisse pris, et la migration suivante attend indéfiniment **sans dire ce qu'elle attend**. Le symptôme est « ça ne rend pas la main » ; la cause n'est devinable par personne. avec la requête `pg_terminate_backend`. Et une phrase qui dit pourquoi la section survit à la correction : la commande n'est plus interactive, mais un `Ctrl+C` au mauvais moment produit le même état. ## Votre option 4, et ce que je n'ai pas fait > un contrôle qui signale les scripts du template susceptibles d'attendre une saisie — c'est une propriété qui se vérifie mécaniquement (stdin fermé, code de sortie) Elle est bonne, et je ne l'ai pas prise — pour une raison que je préfère écrire que taire. Vérifier « ce script attend-il une saisie » demande de **jouer chaque script** avec stdin fermé. Or les scripts d'un satellite montent des bases, appellent des registres, déploient. Un contrôle qui les lance tous pour voir lesquels bloquent est un contrôle qui fait des dégâts en cherchant. Il y aurait une forme statique — chercher les commandes connues pour être interactives (`prisma migrate dev` sans `--name`, `gh` sans `--yes`, `npm login`) — mais c'est une liste à tenir, et vous connaissez déjà mon avis sur les listes à tenir : le prochain outil interactif repassera par la même case. Si vous voyez une troisième voie, elle m'intéresse. En attendant, la correction structurelle vaut pour ce script-ci, et la remarque est consignée. ## Ce que je n'ai pas vérifié moi-même Je n'ai pas rejoué l'invite ni le verrou : la base de développement du gabarit n'est pas levée sur ce poste, et la monter pour reproduire une interruption de migration coûtait plus que ça ne prouvait. Je me suis appuyé sur votre mesure et sur le comportement documenté de Prisma. Ce que j'ai vérifié, c'est le refus : sortie 1, message complet, stdin fermé. Branche `fix/migrations-et-db-dev` sur le gabarit — elle porte aussi [#64](https://git.equilibre-structures.fr/Infrastructure/eqs-platform/issues/64). **Fusionnable tout de suite.**

nicolas-fryder referenced this issue

2026-09-13 04:25:04 +00:00

minimumReleaseAgeExclude rend toute commande pnpm dépendante du réseau, pas seulement l'installation : aucun satellite ne peut jouer sa porte hors ligne #66

nicolas-fryder commented

2026-09-21 06:45:08 +00:00

Author

Owner

Corrigé, côté gabarit. db:dev n'est plus prisma migrate dev nu : c'est node scripts/migrer.mjs, qui traite explicitement le cas non interactif. Son en-tête le dit — « non interactif — un agent de codage, un script, une session sans TTY » — et le message nomme les deux choses qui manquaient : que l'appel reste bloqué, et que l'interrompre laisse le verrou consultatif. Il oriente aussi vers --create-only quand c'est un squelette qu'on veut.

À rapprocher de #64, qui a ouvert l'autre moitié du chemin : refuser-genere laisse désormais passer un squelette --create-only non suivi par git.

Fermé après vérification contre le gabarit à jour le 2026-09-21. Ce ticket restait ouvert faute d'un Closes #63 dans le commit, pas faute de correctif.

Corrigé, côté gabarit. `db:dev` n'est plus `prisma migrate dev` nu : c'est `node scripts/migrer.mjs`, qui traite explicitement le cas non interactif. Son en-tête le dit — « non interactif — un agent de codage, un script, une session sans TTY » — et le message nomme les deux choses qui manquaient : que l'appel **reste bloqué**, et que **l'interrompre laisse le verrou consultatif**. Il oriente aussi vers `--create-only` quand c'est un squelette qu'on veut. À rapprocher de #64, qui a ouvert l'autre moitié du chemin : `refuser-genere` laisse désormais passer un squelette `--create-only` non suivi par git. Fermé après vérification contre le gabarit à jour le 2026-09-21. Ce ticket restait ouvert faute d'un `Closes #63` dans le commit, pas faute de correctif.

nicolas-fryder closed this issue

2026-09-21 06:45:14 +00:00