Migrations

Motoko Base utilise Drizzle Kit pour gérer les migrations de base de données. Le schéma est défini en TypeScript (src/lib/db/schema/) ; Drizzle génère des fichiers SQL de migration et les applique à votre base Postgres.

Les trois commandes sont définies dans package.json :

"db:generate": "drizzle-kit generate",
"db:migrate": "drizzle-kit migrate",
"db:studio": "drizzle-kit studio"

La configuration se trouve dans drizzle.config.ts :

export default defineConfig({
  schema: "./src/lib/db/schema/schema.ts",
  out: "./drizzle/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

DATABASE_URL doit être défini dans .env avant d'exécuter toute commande. Avec Supabase, utilisez la connexion directe (port 5432) si les migrations échouent via le transaction pooler.

pnpm db:generate

Génère un nouveau fichier de migration à partir des différences entre votre schéma TypeScript et le dernier snapshot de migration.

When to use

• Après avoir ajouté ou modifié une table dans src/lib/db/schema/
• Après avoir ajouté des colonnes, des index, des clés étrangères ou des contraintes
• Après avoir exporté un nouveau fichier de schéma depuis schema.ts

When not to use

• Pour appliquer des migrations — utilisez db:migrate à la place
• Pour parcourir les données — utilisez db:studio à la place
• Sur un clone frais sans changements de schéma — il n'y a rien de nouveau à générer

What it does

1. Lit src/lib/db/schema/schema.ts et toutes les tables exportées
2. Compare avec le dernier snapshot dans drizzle/migrations/
3. Crée un nouveau dossier sous drizzle/migrations/ avec :
   • migration.sql — le SQL à exécuter
   • snapshot.json — l'état du schéma pour le prochain diff

Example

Vous avez ajouté une table notes au schéma :

pnpm db:generate

Sortie (exemple) :

drizzle/migrations/20260824120000_some_name/migration.sql

Relisez le SQL généré avant de migrer. Drizzle Kit est précis pour la plupart des changements, mais vérifiez toujours les opérations destructives (drops, renames).

pnpm db:migrate

Applique les migrations en attente à la base connectée via DATABASE_URL.

When to use

• Après pnpm db:generate — pour appliquer votre nouvelle migration
• Après un pull git lorsqu'un coéquipier (ou l'upstream) a ajouté des migrations
• Sur une base fraîche — pour créer toutes les tables from scratch
• Pendant le setup local — juste après le clone (voir Installation)

When not to use

• Quand vous avez modifié le schéma mais n'avez pas encore lancé db:generate — générez d'abord
• Pour inspecter les données — utilisez db:studio

What it does

1. Se connecte à Postgres via DATABASE_URL
2. Exécute tout SQL de migration pas encore enregistré dans le journal de migrations de la base
3. Met à jour le journal pour que la même migration ne soit pas appliquée deux fois

Example

pnpm db:migrate

Lancez ceci après chaque workflow de changement de schéma :

pnpm db:generate && pnpm db:migrate

En CI ou en déploiement production, lancez pnpm db:migrate dans votre étape de release (une fois les variables d'environnement disponibles).

Troubleshooting

pnpm db:studio

Ouvre Drizzle Studio — une UI web locale pour parcourir les tables, voir les lignes et exécuter des requêtes ad-hoc.

When to use

• Inspecter les données pendant le développement (users, links, files, sessions)
• Déboguer si une migration a créé les colonnes attendues
• Vérifier que les sign-ups de test ont écrit les bonnes lignes
• Explorer des tables inconnues après un pull de nouvelles migrations

When not to use

• Pour changer le schéma — éditez les fichiers de schéma TypeScript et lancez db:generate + db:migrate
• En production comme outil d'admin principal — utilisez le Supabase Dashboard ou un admin dédié pour les données de production
• Comme substitut à de vrais scripts de seed — Studio sert à l'inspection, pas au setup reproductible

What it does

Démarre un serveur local (Drizzle Kit affiche l'URL, typiquement https://local.drizzle.studio). Il se connecte avec DATABASE_URL depuis .env.

Example

pnpm db:studio

Gardez le terminal ouvert pendant l'utilisation de Studio. Arrêtez avec Ctrl+C une fois terminé.

Typical workflows

First-time local setup

cp .env.example .env
# fill in DATABASE_URL
pnpm db:migrate
pnpm dev

Pas besoin de db:generate — les migrations sont déjà livrées avec le dépôt.

You changed the schema

# 1. Edit src/lib/db/schema/*.ts and export from schema.ts
pnpm db:generate
pnpm db:migrate
pnpm db:studio   # optional — verify the new table

You pulled new migrations from git

pnpm db:migrate

You want to inspect data without changing anything

pnpm db:studio

Migration files in the repo

Les migrations appliquées vivent dans drizzle/migrations/. Chaque dossier contient :

• migration.sql — SQL exécuté par db:migrate
• snapshot.json — snapshot interne du schéma pour le prochain diff db:generate

Commitez les fichiers de migration dans git. Les coéquipiers et les déploiements de production s'appuient sur le même historique SQL ordonné.

Ne modifiez pas à la main les migrations déjà appliquées en production. Si vous devez corriger une erreur avant que quiconque ait migré, supprimez le dossier de migration non appliqué et régénérez. Si déjà appliquée, créez une nouvelle migration corrective.

Next steps

Adding a New Table — Tutoriel complet : schéma → export → generate → migrate → queries.

Database — Vue d'ensemble de l'architecture, conventions de schéma et motifs de requête.