Base de données et migrations

Vérifié avec le commit e632762 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 run 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 run 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:migrate:prod
pnpm db:check:prod
pnpm db:integrity -- --production

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.

Promouvez le code seulement après avoir vérifié la sauvegarde, testé la migration en staging, obtenu un pnpm db:check:prod réussi sans historique en attente ou divergent, et confirmé la coexistence des anciennes et nouvelles versions.

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é.

Migrer l’authentification avant le déploiement

Cette version utilise Better Auth 1.7.6. Appliquez d’abord la migration SaaS 0037_neat_excalibur.sql : elle ajoute verified, failed_verification_count et locked_until à two_factor. Seules les inscriptions déjà confirmées (users.two_factor_enabled=true) sont marquées vérifiées ; un secret en attente n’est pas une confirmation. Vérifiez l’inscription MFA, le verrouillage après codes erronés et la connexion Admin en staging.

db:check:prod réussit uniquement lorsque toutes les migrations sont appliquées et leurs checksums correspondent ; une histoire en attente ou différente bloque la promotion. db:integrity vérifie relations, valeurs invalides, nullabilité et orphelins sans écriture. Fournissez explicitement les variables de production aux commandes.