Configurer la base de données

Qu'est-ce qu'une migration

Une base de données neuve est vide — elle n'a pas de tables pour les utilisateurs, les espaces de travail ou les enregistrements. Une migration est une modification de base de données enregistrée et ordonnée : un fichier qui dit crée cette table, ajoute cette colonne. Le kit livre ses migrations toutes faites ; la commande db:migrate applique chacune en attente à la base nommée par DATABASE_URL.

L'exécuter n'est pas une installation optionnelle — c'est ce qui transforme un Postgres vide en base de données de votre app. La connexion, les espaces de travail, les enregistrements de facturation et les données enregistrées vivent tous dans ces tables.

C'est pourquoi les comptes cassent si la connexion arrive avant les migrations : l'app écrit le nouvel utilisateur dans une table qui n'existe pas encore, laissant un compte à moitié créé. Migrez toujours d'abord — les étapes d'installation ci-dessous font exactement cela avant la première vraie connexion.

Configuration et paramètres

Avant toute étape, lisez Avant de commencer et Principes de base du terminal. Ces instructions supposent que vous avez ouvert le monorepo supastack complet dans VS Code ; sa racine package.json marque la racine du référentiel. Dans les commandes pnpm, un package d'espace de travail est une application ou un dossier de code partagé ; dans le produit, un espace de travail est le conteneur de données et la limite de sécurité d'une équipe. corepack pnpm --filter ... sélectionne un package dans le monorepo tandis que les commandes sont exécutées à partir de sa racine. Si vous avez ouvert uniquement un dossier mobile ou de bureau synchronisé, il ne contient pas le backend Web, la configuration Docker ou les scripts racine : exécutez le backend à partir de ce monorepo ou d'un serveur hébergé accessible et utilisez les propres scripts du dossier de plateforme. Une variable d'environnement est un paramètre nommé stocké dans un fichier .env local ou dans votre tableau de bord d'hébergement ; redémarrez l'application concernée après l'avoir modifiée et conservez les secrets du serveur en dehors des valeurs NEXT_PUBLIC_ et EXPO_PUBLIC_.

1. Installez et démarrez Docker Desktop.

2. Copiez .env.example dans .env à la racine pour les outils de migration et dans apps/web/.env.local pour Next.js (PowerShell : Copy-Item .env.example .env ; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash : cp .env.example .env ; cp .env.exemple apps/web/.env.local). Gardez DATABASE_URL identique dans les deux fichiers ; l'exemple correspond déjà à la base de données Docker locale.

3. À partir de la racine du référentiel, exécutez docker compose up -d postgres et docker compose ps ; attendez que postgres soit sain.

4. Exécutez le corepack pnpm --filter @supastack/db db:migrate à partir de la racine pour appliquer les migrations déjà fournies avec le kit. Seulement après avoir modifié packages/db/src/schema.ts, exécutez db:generate, inspectez le SQL généré, puis exécutez db:migrate. Attendu : le conteneur Postgres local est sain et l'application Web utilise sa base de données migrée. Ne dirigez jamais cette première exécution vers la production.

Configurez DATABASE_URL vers la base Postgres prévue dans l’environnement serveur. Utilisez une base jetable distincte pour les tests d’intégration. Ne ciblez jamais une base de production avec les migrations de test.

L’espace de travail de base de données exporte les définitions de schéma et les helpers de persistance. Examinez packages/db/src/schema.ts et le répertoire des migrations avant d’ajouter une table ou une colonne.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

Commandes à copier

Suivez les commentaires pour voir dans quel dossier une commande s'exécute. Si deux terminaux sont étiquetés, ouvrez deux fenêtres de terminal et laissez la première commande s'exécuter pendant que vous utilisez la seconde.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Processus d’implémentation

Après la modification du schéma, générez une migration, examinez le SQL produit et versionnez-la avec le changement de schéma. Prévoyez comment renseigner les enregistrements existants avant d’ajouter une colonne obligatoire.

Ajoutez workspaceId à chaque enregistrement détenu par un utilisateur et appliquez cette portée aux lectures et écritures. Utilisez l’historique immuable des prix des modèles pour la comptabilité de l’IA au lieu de réécrire les prix associés aux enregistrements d’utilisation existants.

Vérification et dépannage

Si Docker indique qu'il ne peut pas se connecter à son moteur, démarrez Docker Desktop et attendez la fin du chargement. Si postgres n'est pas sain, exécutez docker compose logs postgres à partir de la racine et corrigez cette erreur avant de migrer. Si Web indique que DATABASE_URL est manquant, vérifiez apps/web/.env.local ; si db:migrate ne parvient pas à se connecter, vérifiez le fichier .env racine. Si vous modifiez les bases de données, mettez à jour les deux fichiers. Lisez la première instruction de migration ayant échoué avant de réessayer ; ne le répétez jamais contre la production.

Appliquez les migrations à une base isolée et exécutez-y les tests qui exigent une base. L’absence d’identifiants doit produire un état explicitement ignoré, et non prétendre que la persistance a été validée. Si une migration échoue, examinez l’instruction en échec et le schéma actuel avant de réessayer.