# Prisma — schéma et migrations explicites

Le workspace privé `@data-asso/prisma` fournit le [modèle](../domains/referentiel-associations.md), une migration initiale pour base neuve et un client serveur. Voir les [preuves du lot 22403](../work-items/22403-schema-prisma.md). Le lot 22403 ne livre aucun importeur, seed métier ou application. Le lot [22407](../work-items/22407-waldec.md) ajoute séparément la [CLI WALDEC](waldec.md), sans modifier ce schéma.

## Installation et génération

À la racine, avec les accès npm configurés dans la session sans afficher leur valeur :

```sh
nvm use
PRISMA_SKIP_POSTINSTALL_GENERATE=true corepack yarn install --immutable
corepack yarn prisma:validate
corepack yarn build:prisma
corepack yarn typecheck
```

Node 24.22.2, Yarn 4.18.1, TypeScript 5.9.3 ; prisma, client et adapter-pg 7.10.1, pg 8.16.3 et types pg 8.16.0. Un seul lockfile racine. Deux resolutions racine ciblées sur les dépendances de l’adaptateur imposent aussi pg 8.16.3 / types pg 8.16.0 dans ce chemin runtime, sans résolution globale. Les dépendances internes futures seront déclarées `workspace:*`. `build:prisma` exécute `prisma:generate` puis compile les sources générées et le client dans dist. Pour seulement générer, utiliser `prisma:generate`. Aucune génération implicite n’est attendue à l’installation ; ne pas lancer deux générations équivalentes sans changement. Générer/compiler avant les consommateurs. Les sorties générées/dist sont ignorées.

## Configuration locale et migration

La procédure [Compose locale](sites-documentaires.md#compose-local--22400) prépare `.env.docker` dans chaque worktree. Choisir les ports et les identifiants du PostgreSQL autorisé. Les commandes utilisent la configuration de ce fichier en priorité sur le shell.

| Contexte | URL construite |
| --- | --- |
| CLI Prisma et client depuis l’hôte | localhost et POSTGRES_PORT |
| CLI Prisma et client des traitements dans Docker | postgres:5432 |

`POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_PORT` viennent de la configuration du worktree. Les identifiants sont encodés comme composants URI. Garder la connexion résolue dans le processus qui l’utilise. Validate/generate utilisent une configuration synthétique hors ligne.

Sur une **base neuve autorisée** ou dans un environnement dont l’évolution est autorisée :

```sh
corepack yarn prisma:migrate:deploy
corepack yarn prisma:migrate:status
```

Deploy applique les migrations versionnées, status consulte leur état. Cette procédure ne bascule pas une base historique ; aucune commande ci-dessus n’a été exécutée sur la base préexistante du développeur lors de 22403. Un schéma technique sain ne signifie pas que les données métier sont prêtes.

Pour créer une migration en développement, prévoir explicitement une shadow database sur la même instance locale et le même port, avec un autre nom de base. Fournir sa connexion dans SHADOW_DATABASE_URL via la session, puis :

```sh
corepack yarn prisma:migrate:create --name evolution_nom_simple
```

La commande appelle `migrate dev --create-only`. Elle refuse l’absence de shadow, les noms de base identiques (y compris alias localhost/127.0.0.1/::1) et les arguments de reset/force. Relire et compléter le SQL avant deploy. En cas de drift ou proposition de reset, arrêter et diagnostiquer ; ne pas acquitter automatiquement. `db push` et reset ne sont pas exposés. Pour le premier SQL hors base, la CLI épinglée nécessite aussi une datasource dans sa config ; ne pas prendre un fichier SQL vide pour une génération réussie.

Les CHECK et cinq unicités partielles courantes sont dans la migration SQL ; ne pas les supprimer au motif qu’ils ne figurent pas en @@unique. Toute évolution doit préserver leurs définitions/comportements et rejouer les migrations sur une shadow distincte. Ne pas modifier une migration déjà appliquée ; en créer une nouvelle.

### Déployer et contrôler depuis Docker

Depuis le worktree configuré, pour une base neuve ou une évolution autorisée :

```sh
corepack yarn docker:jobs migrate:deploy
corepack yarn docker:jobs migrate:status
```

Le script construit l’image data-jobs, attend la disponibilité de PostgreSQL, puis lance un conteneur ponctuel sur le réseau du projet. Il applique les mêmes migrations versionnées que le wrapper hôte. Le conteneur est supprimé en fin d’exécution. Le statut à jour permet de passer à la [synchronisation WALDEC](waldec.md#synchroniser-dans-docker).

La construction de cette image utilise les dépôts Debian Bookworm pour OpenSSL et la distribution des moteurs de Prisma. OpenSSL est présent dans le builder et le runtime. [Prérequis système de Prisma](https://www.prisma.io/docs/orm/v7/reference/system-requirements#linux-runtime-dependencies).

Si une migration échoue ou si son résultat est incertain, suspendre la synchronisation. Consulter le code de sortie et les diagnostics Prisma, puis contrôler la cible, `migrate:status` et l’historique `_prisma_migrations` avant de décider d’une correction ou d’une relance. Pour une erreur de connexion, vérifier en particulier que le fichier local correspond aux identifiants du volume déjà initialisé. Le volume est conservé pendant le diagnostic.

## Client Node et validations

Après build, importer `createDatabaseClient` depuis `@data-asso/prisma`. Passer `connectionString` explicitement. La fonction `databaseUrl` de `@data-asso/prisma/config` construit les cibles hôte et conteneur à partir des valeurs fournies. Le pool de l’adaptateur a un maximum de 5 connexions par défaut, un délai de connexion de 5 s et une durée d’inactivité de 10 s. Les jobs ferment leur pool en finally avec `await client.$disconnect()`. Le lecteur WALDEC de common réutilise le pool jusqu’à l’arrêt du processus Next. Aucun client n’est créé à l’import. Les composants et adaptateurs Next passent par le métier pour lire la base.

```sh
corepack yarn test:prisma:config
corepack yarn test:prisma:integration
```

En local, la suite d’intégration exige Docker et échoue si le daemon est indisponible. Elle crée son réseau et son conteneur PostgreSQL 18.0, avec un port loopback aléatoire et un tmpfs. En cas d’interruption avant nettoyage, inspecter les ressources portant l’étiquette `dataasso.prisma-test` de la campagne et supprimer uniquement leurs identifiants.

Le [job GitLab 22444](../work-items/22444-regles-pipeline-ci.md#postgresql-jetable) appelle la même suite avec `--gitlab-postgres`. Il vérifie l’identité et l’état neuf de son service PostgreSQL sur le loopback du pod avant la migration. Les deux modes utilisent des fixtures synthétiques et ferment leurs connexions. Leur configuration de connexion est construite par la suite, indépendamment du `.env.docker` du worktree et des URL héritées.

La migration, la synchronisation de référentiels, les seeds et la reprise historique sont quatre opérations séparées. Le lot 22403 ne réalise pas les trois dernières ; 22407 livre seulement la synchronisation explicite de nomenclature WALDEC. Aucun téléchargement d’associations RNA/SIRENE ni faux référentiel géographique ; le petit snapshot de nomenclature WALDEC relève du lot distinct 22407.
