Setup base de données Neon

Contexte

Neon est une base PostgreSQL serverless entièrement managée. Le CLI neonctl permet de créer des branches de DB, gérer les connexions, et exporter les connection strings. Idéal pour un workflow de développement avec environnements séparés (dev/staging/prod).

Prérequis

Compte Neon actif (gratuit)
neonctl CLI installée : npm i -g neonctl
Authentication Neon : neonctl auth

Étapes

1. Installer neonctl

npm i -g neonctl
neonctl auth

Suit les prompts de connexion au navigateur.

2. Créer un projet Neon (optionnel)

Généralement fait via le dashboard, mais possible via CLI :

neonctl projects create --name my-app-db

3. Lister les branches existantes

neonctl branches list

# Output:
# Branch    ID    Current    Region
# main      xxxx  yes        us-east-1

4. Créer une branche de développement

neonctl branches create --name dev

# Output:
# Successfully created branch dev

5. Récupérer la connection string

neonctl connection-string --branch dev

# Output:
# postgresql://user:password@project-dev.neon.tech:5432/dbname

Ajouter cette string dans .env.local :

DATABASE_URL=postgresql://user:password@project-dev.neon.tech:5432/dbname

6. Vérifier la connexion

Avec un ORM (Prisma) :

npx prisma db push --skip-generate
# ✓ Schema pushed to dev branch

Ou via psql :

psql postgresql://user:password@project-dev.neon.tech:5432/dbname

# Si psql absent:
# brew install postgresql (macOS)
# apt install postgresql-client (Linux)

Workflow multi-environnements

Dev branch

neonctl branches create --name dev
neonctl connection-string --branch dev > .env.dev

Staging branch

neonctl branches create --name staging
neonctl connection-string --branch staging > .env.staging

Production (main)

# Utiliser directement la branche 'main' existante
neonctl connection-string --branch main > .env.prod

Migrações avec Prisma

# Push schema local sur dev
npx prisma db push --skip-generate

# Créer une migration
npx prisma migrate dev --name add_dashboard_table

# Pusher en prod
DATABASE_URL=<prod-url> npx prisma migrate deploy

Exemple complet

# 1. Create dev branch
neonctl branches create --name dev

# 2. Get connection string
DEV_URL=$(neonctl connection-string --branch dev)

# 3. Add to .env.local
echo "DATABASE_URL=$DEV_URL" >> .env.local

# 4. Push schema
npx prisma db push

# 5. Verify
psql $DEV_URL -c "SELECT version();"

Suppression de branches

neonctl branches delete --name dev

# Verification
neonctl branches list

Commandes courantes

neonctl branches list              # Lister toutes les branches
neonctl branches create --name X   # Créer branche X
neonctl branches delete --name X   # Supprimer branche X
neonctl connection-string          # String pour la branche courante
neonctl connection-string --branch X  # String pour branche X

Troubleshooting

Symptôme	Cause probable	Résolution
Connection refused	Branche n’existe pas	Vérifier avec `neonctl branches list`
Auth expired	Token expiré	`neonctl auth` pour reconnecter
Migrations échouent	Restrictions Neon	Vérifier les quotas gratuit

Variantes

Auto-branching : Vercel + Neon = branche DB par preview
Point-in-time restore : Récupérer un backup d’une date spécifique
Pooling : Neon inclut un connection pooler gratuit

Voir aussi

30-vercel-deploy.md — Déployer avec Vercel
28-task-runner-feature.md — Implémenter features avec DB