Base de données et migrations

Vérifié avec le commit 2a1a04a du starter.

À la fin, vous saurez quelle base utiliser dans chaque environnement, transformer une modification du schéma en SQL révisable et l’appliquer séparément de la version applicative.

Le starter choisit délibérément PostgreSQL avec Drizzle plutôt que plusieurs adaptateurs. En local, pnpm setup peut lancer PostgreSQL dans Docker ; en production, choisissez un PostgreSQL compatible, managé ou auto-hébergé, puis définissez DATABASE_URL. src/db/schema.ts est la source du schéma et les SQL versionnés de src/db/migrations/ son historique déployable. Seul src/models/** peut appeler db().

Flux local

pnpm setup crée des bases de développement et de test séparées. Le nom de test doit contenir test ; le garde-fou refuse de vider toute autre base.

Après un changement de schéma :

pnpm db:generate
pnpm db:lint
pnpm db:migrate
pnpm test:db:setup
pnpm test:db

Commitez le SQL généré et meta/_journal.json avec le code. Ne modifiez jamais une migration déjà déployée.

Production

Les migrations ne sont jamais automatiques au déploiement. C’est le choix de sécurité livré : base et application peuvent être observées, relancées et publiées séparément.

pnpm db:check:prod
pnpm db:migrate:prod
pnpm db:integrity

L’outil non interactif prend un advisory lock PostgreSQL et vérifie les checksums. Sauvegardez d’abord et appliquez expand/contract afin que versions actuelle et suivante coexistent pendant les déploiements séparés.

Conventions

• id reste interne ; les API publiques utilisent uuid.
• L’argent est stocké en unités mineures entières avec sa devise.
• Les données tenant portent org_uuid et chaque requête modèle le filtre.
• Clés d’idempotence et numéros de transaction sont uniques en base.
• Les identités restent logiques car l’effacement utilise des pseudonymes irréversibles. Les relations tâche vers registre, job et fichier sont contraintes ; lifecycle garde l’ordre de suppression.
• Les réservations ajoutent une contrainte d’exclusion PostgreSQL contre les créneaux qui se chevauchent.

Choix à faire avant la production

• Choisissez qui lance les migrations : un job CI de release ou un opérateur. Ne les exécutez pas depuis chaque instance web.
• Définissez une politique de sauvegarde et restauration adaptée à vos données ; le verrou de migration ne remplace pas une sauvegarde.
• Exécutez db:integrity avant et après une relation. Le linter refuse drop destructif, rename risqué, réécriture sans limite et index unique bloquant sans exception documentée.
• Préférez expand/contract pour une release sans interruption. Un renommage destructif en une étape est plus simple, mais couple schéma et code et rend le rollback dangereux.

Vous êtes prêt lorsque pnpm db:check:prod montre exactement les migrations attendues, que la sauvegarde est récente, que la migration a été testée sur une copie de staging et que les anciennes et nouvelles versions peuvent coexister pendant le déploiement.

Lisez docs/database.md et DEPLOYMENT.md du starter avant de modifier les contrats de données.

Avant de modifier les tables : relisez Architecture et contrats d’erreur et Authentification des clients pour préserver les frontières de couche et d’identité.