> ## Documentation Index
> Fetch the complete documentation index at: https://api-documentation.kare-app.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrations DB

> Où tournent les migrations, et pourquoi elles doivent être réversibles

## Où elles tournent

Les migrations sont appliquées par le **pipeline de déploiement**, jamais par l'image au démarrage.

```mermaid theme={null}
flowchart LR
    B[build image SHA7] --> M["migrate<br/>prisma migrate deploy"]
    M --> U["update image du container"]
```

Le job `migrate` de `deploy-api.yml` tourne **avant** le flip d'image, et est sérialisé par job
concurrency sur le stage. Le runner atteint Postgres via l'accès public restreint à la CIDR du
migration runner (voir [Infrastructure](/devops/infrastructure)).

## Le piège du rollback

```mermaid theme={null}
flowchart LR
    I["image : recule vers v1.3.0"]
    D["base : reste migrée"]
```

Une migration destructive casse le rollback : l'ancienne image cherche une colonne disparue.

## La règle : expand / contract

À tout instant, **l'ancienne et la nouvelle image doivent fonctionner avec le schéma en place**.

<Tabs>
  <Tab title="Interdit">
    ```sql theme={null}
    ALTER TABLE users RENAME COLUMN email_address TO email;
    ```

    L'image précédente plante instantanément. Aucun rollback possible.
  </Tab>

  <Tab title="Expand / contract">
    1. **Expand** — ajouter `email`, le code écrit dans les deux colonnes. Rollback OK.
    2. Le nouveau code ne lit plus `email_address`. Déployé, observé.
    3. **Contract** — supprimer `email_address` quand plus personne ne l'utilise.

    Un changement risqué se fait donc en 2 ou 3 PR.
  </Tab>
</Tabs>

## Règles pratiques

* Toujours générer une migration quand le schéma bouge :
  `yarn workspace @kare/database migrate:dev --name <description>`.
* Ne **jamais** éditer une migration déjà commitée.
* Les migrations de données vivent dans `apps/api/database/data-migrations/`, comme scripts autonomes.
* Une base restaurée depuis un dump ne fait pas reculer les images : après une restauration, vérifier
  que les containers tournent sur une image compatible.