Supabase CLI : du développement local à la production

La Supabase CLI fait tourner toute la pile Supabase sur votre machine (Postgres, Auth, Storage, Realtime, Edge Functions, Studio), capture vos changements de schéma sous forme de migrations SQL versionnées et les pousse vers votre projet hébergé. Pourquoi cela compte : vous testez chaque changement de base de données sur une copie jetable avant qu'il touche vos vrais utilisateurs, et vous pouvez rejouer ou annuler un déploiement sans improviser. Le cycle de base tient en cinq commandes : supabase init, supabase start, supabase db diff -f, supabase db reset, supabase db push. Ce guide va du poste de travail à la production : installation et Docker, migrations, déploiement par la CI, sauvegardes et checklist de mise en ligne. Il signale aussi les pièges des anciennes versions (installation npm globale, Inbucket, functions logs, db push --project-ref) qui circulent encore dans beaucoup de tutoriels.

Comment installer la Supabase CLI ?

Deux modes coexistent¹ : une installation globale (Homebrew sur macOS et Linux, Scoop sur Windows, paquets Linux) qui fournit la commande supabase, ou une dépendance de projet via npm, pnpm, yarn ou bun, qui s'exécute ensuite avec npx supabase. L'installation npm globale (npm install -g supabase) n'est pas une méthode prise en charge.

# macOS / Linux (Homebrew)
brew install supabase/tap/supabase

# Windows (Scoop)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

# Dépendance de projet (version épinglée dans package.json)
npm install supabase --save-dev
npx supabase --version

En dépendance de projet, la CLI exige Node.js 20 ou plus récent ; les versions plus anciennes ne sont pas prises en charge¹. C'est le mode à privilégier en équipe : tout le monde utilise la même version, fixée dans package.json. La branche 2.x est la version actuelle ; supabase --version affiche celle que vous avez installée. Mise à jour : brew upgrade supabase, scoop update supabase ou npm update supabase --save-dev. Dans la suite, les exemples sont écrits supabase <commande> ; ajoutez npx devant si la CLI est installée dans le projet.

Que faut-il avant de lancer la pile locale ?

• Un moteur de conteneurs compatible Docker : Docker Desktop, ou une alternative citée par la documentation (Rancher Desktop, Podman, OrbStack, colima)¹. Il doit être démarré avant supabase start.
• De la mémoire : la documentation recommande au moins 7 Go de RAM pour lancer tous les services².
• Node.js 20 ou plus récent, seulement si la CLI passe par npm ou npx¹.
• Git, pour versionner le dossier supabase/ et vos migrations.

Comment démarrer un environnement Supabase local ?

# Crée le dossier supabase/ (config.toml, migrations…), à versionner dans git
supabase init

# Télécharge les images au premier lancement, puis démarre la pile
supabase start

# Exclure des services inutiles pour alléger la machine
supabase start -x imgproxy

# Afficher les URL et clés locales (ou les exporter au format .env)
supabase status
supabase status -o env

# Arrêter sans perdre les données locales
supabase stop

# Arrêter ET effacer les données locales
supabase stop --no-backup

Lancez ces commandes depuis le dossier initialisé par supabase init. Le premier démarrage est plus long : la CLI télécharge toute la pile et quelques images annexes (serveur d'e-mails de test, outil de comparaison de bases)¹. Avec les ports par défaut, un seul projet local peut tourner à la fois sur une machine, car tous les config.toml utilisent les mêmes ports¹ ; pour en lancer deux, ou si un port est déjà pris, changez les ports dans supabase/config.toml, puis relancez supabase stop et supabase start. L'option -x (ou --exclude) saute les conteneurs que vous n'utilisez pas².

Les ports par défaut¹ :

Pour atteindre la base locale depuis une Edge Function qui tourne elle-même dans Docker, remplacez localhost par host.docker.internal¹.

Que deviennent les données locales ?

Elles survivent à supabase stop, mais pas à supabase stop --no-backup, qui supprime les volumes de données locaux¹, ni à supabase db reset, qui recrée la base à partir des migrations et du seed. Sauvegardez ce qui compte avant.

Quelles clés mettre dans les variables d'environnement ?

Les versions récentes affichent des clés au nouveau format (sb_publishable_… et sb_secret_…) au lieu des anciennes clés anon et service_role¹. Ces clés ne valent que pour l'instance locale : elles n'ont aucun lien avec celles de votre projet hébergé, que l'on trouve dans son tableau de bord. Supabase a annoncé la dépréciation des anciennes clés d'ici la fin de 2026¹¹. Pour une application Next.js, la documentation propose ces noms¹¹ :

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...   # copiée depuis supabase status
SUPABASE_SECRET_KEY=sb_secret_...                         # jamais de préfixe NEXT_PUBLIC_

Le préfixe NEXT_PUBLIC_ expose la variable au navigateur : il ne doit jamais servir pour la clé secret.

Où voir les e-mails envoyés par Auth en local ?

Les e-mails de confirmation, de réinitialisation de mot de passe et les liens magiques ne partent pas vers de vraies boîtes : ils sont capturés par Mailpit, accessible sur le port 54324¹. Les anciennes versions de la CLI utilisaient Inbucket sur le même port ; si un tutoriel parle d'Inbucket, il est antérieur à ce changement.

Le Studio local est-il le même que le tableau de bord en ligne ?

Pas tout à fait : l'environnement local ne gère pas toutes les fonctions de la plateforme, et les réglages du projet (Auth par exemple) se modifient dans supabase/config.toml, pas dans le Studio local¹². Relancez la pile après avoir changé ce fichier.

Comment relier le projet local à un projet hébergé ?

# Authentification (ouvre le navigateur, ou utilise SUPABASE_ACCESS_TOKEN)
supabase login

# Lister vos projets pour retrouver la référence
supabase projects list

# Lier le dossier courant à un projet
supabase link --project-ref <project-ref>

db push, db pull et db dump exigent un projet lié². En CI, fournissez le mot de passe de la base par la variable SUPABASE_DB_PASSWORD pour éviter l'invite interactive.

Comment gérer les migrations au quotidien ?

Une migration est un fichier SQL horodaté dans supabase/migrations/ (<timestamp>_<nom>.sql). Le projet distant garde la trace des migrations appliquées dans la table supabase_migrations.schema_migrations ; db push saute celles qui y figurent déjà².

Cycle type pour une nouvelle fonctionnalité

# 1. Modifier le schéma localement (Studio ou SQL)
# 2. Capturer l'écart dans une migration
supabase db diff --schema public -f ajout_table_products

# 3. Relire le SQL généré avant de le committer
cat supabase/migrations/*_ajout_table_products.sql

# 4. Vérifier que tout se rejoue proprement depuis zéro
supabase db reset

# 5. Contrôler puis appliquer au projet lié
supabase db push --dry-run
supabase db push

Relire le fichier généré n'est pas une formalité. Avec le moteur historique migra, db diff peut rater des changements de publication, de buckets Storage ou de vues security_invoker². Les projets initialisés récemment utilisent par défaut le moteur pg-delta ([experimental.pgdelta] enabled = true dans config.toml) ; les projets plus anciens restent sur migra sauf activation explicite. Faites ces modifications visuelles uniquement sur la base locale : un changement fait directement sur la base distante (éditeur SQL ou Table Editor) contourne l'historique et fait échouer le prochain db push avec des erreurs de synchronisation⁴.

Écrire une migration à la main

supabase migration new create_posts_table
# éditer supabase/migrations/<timestamp>_create_posts_table.sql
supabase migration up        # applique les migrations en attente en local
supabase db reset            # ou : repart de zéro, migrations + supabase/seed.sql

Un exemple de contenu, avec les droits (grants) et la RLS dans la même migration que la table, comme le recommande la documentation :

create table public.posts (
  id bigint generated always as identity primary key,
  author_id uuid not null references auth.users (id) on delete cascade,
  title text not null,
  created_at timestamptz not null default now()
);
create index posts_author_id_idx on public.posts (author_id);

alter table public.posts enable row level security;
revoke all on table public.posts from anon, authenticated;
grant select, insert, update, delete on table public.posts to authenticated;

create policy "Authors manage their posts" on public.posts
for all to authenticated
using ( (select auth.uid()) = author_id )
with check ( (select auth.uid()) = author_id );

Pour comprendre chaque ligne de cet exemple (types, index, policies), voyez notre guide base de données et accès aux données, et pour les policies en détail le guide RLS.

Décrire le schéma cible plutôt que les changements

Sur le moteur pg-delta, vous pouvez décrire l'état voulu dans des fichiers supabase/schemas/*.sql et laisser la CLI générer la migration avec supabase db schema declarative sync -f <nom> --no-apply. Ces fichiers font alors foi : la commande les compare à l'historique des migrations, pas à la base vivante, et tout changement fait par Studio, l'éditeur SQL ou psql est ignoré⁵. Les commandes db schema declarative ne tournent pas sur l'ancien moteur ; sur migra, on reste sur db diff -f.

Comment pousser vers staging puis production ?

db push n'accepte pas d'option --project-ref : il cible le projet lié, ou une base précise via --db-url³. Ses options sont --linked, --local, --db-url, --dry-run, --include-all, --include-roles, --include-seed et --password. Pour enchaîner deux environnements, on relie successivement le dossier à chacun, ou on passe l'URL de connexion :

# Staging
supabase link --project-ref "$STAGING_REF"
supabase db push

# Production, après validation
supabase link --project-ref "$PROD_REF"
supabase db push

# Variante sans changer le lien
supabase db push --db-url "$PROD_DB_URL"

db push applique les migrations au projet que vous avez lié, quel qu'il soit : c'est la production seulement si c'est celui-là que vous avez lié. Les fichiers s'appliquent dans l'ordre de leur horodatage : une seule personne doit pousser à la fois, car deux pushes concurrents peuvent entrer en conflit⁴.

Peut-on revenir en arrière ?

Il n'existe pas de fichier de migration « down ». Selon l'endroit :

• En local : supabase migration down --last 1 annule la dernière migration appliquée sur la base ciblée (options --local, --linked, --db-url), et supabase db reset --version <timestamp> repart jusqu'à une version donnée². Ne les lancez pas sur une production : avec --linked ou --db-url, db reset supprime tous les objets créés par l'utilisateur sur la base distante².
• En production : on écrit une migration corrective (un drop column, la restauration d'une contrainte). Pour une erreur qui a détruit des données, il faut une sauvegarde (voir plus bas).
• Historique faux : supabase migration repair --status applied|reverted <timestamp> corrige la table de suivi quand la base est déjà dans le bon état, sans exécuter de SQL⁴.

Que faire quand db push refuse de s'exécuter ?

supabase migration list      # compare les versions locales et distantes
supabase db pull             # si quelqu'un a modifié la base distante à la main
supabase migration repair --status applied 20260930120000

Avec pg-delta, db pull capture aussi vos personnalisations dans les schémas gérés par Supabase, comme un trigger sur auth.users qui appelle une fonction de public⁴. Un trigger dont la fonction vit dans auth ou storage reste exclu : livrez-le par une migration versionnée écrite à la main.

Quelles règles d'équipe adopter ?

• Aucun changement de schéma directement sur la base distante, même minime.
• Une migration déjà appliquée en production ne se modifie plus : on en ajoute une nouvelle.
• Grants, RLS et policies dans la même migration que la table.
• supabase migration squash fusionne l'historique local, mais omet les instructions de données (insert, update, delete), les tâches cron, les buckets Storage et les secrets du vault : il faut les rajouter à la main².
• Pour tester une migration sur une copie isolée avant la production, utilisez le branching (voir plus bas).

Comment générer les types TypeScript ?

# Depuis la base locale
supabase gen types typescript --local > src/types/database.types.ts

# Depuis le projet hébergé
supabase gen types typescript --project-id "$PROJECT_REF" --schema public > src/types/database.types.ts

# Syntaxe équivalente avec --lang
supabase gen types --lang=typescript --linked > src/types/database.types.ts

Les deux syntaxes figurent dans la documentation². La commande sait aussi produire des types Go, Swift et Python. Ajoutez un script "gen:types" dans package.json et relancez-le après chaque migration ; le workflow de CI de la documentation vérifie d'ailleurs que les types générés sont bien commités⁶.

Comment développer et déployer les Edge Functions ?

# Créer supabase/functions/ma-fonction/index.ts
supabase functions new ma-fonction

# Servir toutes les fonctions localement, avec un fichier de secrets local
supabase functions serve --env-file supabase/functions/.env

# Déboguer avec l'inspecteur V8 (Chrome DevTools, VS Code)
supabase functions serve --inspect-mode brk

# Déployer (une fonction ou toutes)
supabase functions deploy ma-fonction
supabase functions deploy --project-ref "$STAGING_REF"

La CLI n'a pas de commande functions logs : les journaux des fonctions hébergées se consultent dans la section Functions du tableau de bord. Contrairement à db push, functions deploy accepte --project-ref². Plus de détails dans notre guide des Edge Functions Supabase.

Comment gérer les secrets ?

# Un secret
supabase secrets set STRIPE_SECRET_KEY=sk_live_xxx

# Tout un fichier .env
supabase secrets set --env-file ./supabase/.env.production

# Lister (noms et empreintes, pas les valeurs)
supabase secrets list

# Supprimer
supabase secrets unset STRIPE_SECRET_KEY

Ces secrets sont poussés vers le projet lié et destinés aux Edge Functions². Ne committez jamais le fichier .env qui les contient.

Comment déployer en production ?

Pour mettre un projet Supabase en production, cinq points font l'essentiel du travail : RLS et droits vérifiés sur chaque table exposée, clés secrètes uniquement côté serveur, plan payant (pas de mise en pause, sauvegardes quotidiennes), migrations appliquées par la CI plutôt qu'à la main, et un mode de connexion adapté à chaque client. Supabase publie sa propre checklist de production ; les sections qui suivent la reprennent et la classent⁷.

Que vérifier avant d'ouvrir l'application au public ?

Sécurité des données

• RLS activée sur toutes les tables exposées, avec des policies raisonnables : sans elles, n'importe quel client peut lire et modifier les données⁷. Détails dans notre article sur les policies RLS et leurs tests.
• Droits (grants) contrôlés : selon les droits par défaut de votre projet, une table créée dans public peut être joignable par l'API sans que vous l'ayez décidé. Révoquez ce qui ne doit pas l'être (commandes dans notre guide base de données).
• Clés : la clé secrète (sb_secret_…) contourne toute RLS et ne sort jamais du serveur. Les anciennes clés anon et service_role sont dépréciées d'ici fin 2026 : prévoyez la migration vers les clés publishable et secret avant la mise en ligne plutôt qu'après¹¹.
• Conseiller de sécurité (Security Advisor) du tableau de bord passé en revue, SSL imposé et restrictions réseau activées sur la base⁷.

Compte et authentification

• MFA sur votre compte Supabase (et 2FA sur GitHub si vous vous connectez avec GitHub), et plusieurs propriétaires dans l'organisation⁷.
• Confirmation d'e-mail activée, durée de validité des codes à usage unique réglée à 3 600 secondes ou moins⁷.
• Serveur SMTP personnel pour les e-mails d'authentification : par défaut, les endpoints qui envoient des e-mails sont limités à 2 e-mails par heure ; avec un SMTP personnel, la limite par défaut est de 30 nouveaux utilisateurs par heure, réglable dans les limites de débit d'Authentication⁷.

Performance et disponibilité

• Index adaptés aux requêtes fréquentes, test de charge (par exemple avec k6) sur un environnement de préproduction⁷.
• Point-in-Time Recovery (PITR) activé si la base doit dépasser 4 Go⁷.
• Limites Realtime et Edge Functions de votre plan relues si l'application en dépend.

Quel plan Supabase pour la production ?

Le plan Free met les projets en pause après une semaine d'inactivité et ne comprend aucune sauvegarde automatique : il ne convient pas à une application en production⁸.

Tarifs relevés sur la page officielle le 7 octobre 2026, hors taxes et hors consommation (calcul, disque, bande passante)⁸. Pour le détail des coûts, voir Supabase Pricing.

Comment séparer développement, préproduction et production ?

Le schéma classique reste un projet Supabase par environnement (dev, staging, prod), les migrations versionnées dans supabase/migrations servant de source unique⁶. Sur un plan payant, le branching crée en plus un environnement de prévisualisation par branche Git pour tester une migration avant la production ; il est facturé 0,01344 $ par branche et par heure⁸.

Comment appliquer les migrations avec GitHub Actions ?

Le workflow officiel lie le projet puis pousse les migrations. Il attend trois secrets : un jeton d'accès personnel restreint aux projets concernés, le mot de passe de la base et la référence du projet⁶. La documentation propose trois workflows : une vérification sur chaque pull request (la pile locale démarre et le schéma est contrôlé, les types générés doivent être commités), un déploiement vers la préproduction à chaque push sur develop, et un déploiement vers la production à chaque push sur main⁶.

# .github/workflows/production.yml
name: Deploy to Production

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
      SUPABASE_DB_PASSWORD: ${{ secrets.PRODUCTION_DB_PASSWORD }}
      SUPABASE_PROJECT_ID: ${{ secrets.PRODUCTION_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: supabase/setup-cli@v1
        with:
          version: latest
      - run: supabase link --project-ref $SUPABASE_PROJECT_ID
      - run: supabase db push
      - run: supabase functions deploy --project-ref $SUPABASE_PROJECT_ID

Dupliquez le job pour la préproduction (branche develop, secrets de staging) et faites passer vos tests entre les deux. Alternative sans workflow : l'intégration GitHub du tableau de bord, qui déploie la branche main⁷. La référence du projet se donne à supabase link, jamais à db push.

Quelle chaîne de connexion utiliser ?

Supabase propose plusieurs modes de connexion. Le pooler partagé s'appelle Supavisor ; PgBouncer n'est plus utilisé que pour le pooler dédié des plans payants¹⁰.

Trois pièges : via le pooler partagé, l'utilisateur est postgres.[PROJECT-REF] et non postgres ; le mode transaction ne supporte pas les requêtes préparées (prepare: false avec Postgres.js, pgbouncer=true avec Prisma) ; et l'index du cluster dans l'hôte ne se déduit pas de la région, copiez-le depuis le bouton Connect du tableau de bord¹⁰. Une chaîne db.[ref].supabase.co:6543?pgbouncer=true ne correspond qu'au pooler dédié, pas au pooler partagé par défaut.

Comment surveiller les performances ?

La CLI regroupe des requêtes de diagnostic sous supabase inspect db ; supabase inspect db outliers liste les requêtes qui consomment le plus de temps d'exécution cumulé². Les compteurs de pg_stat_statements sont cumulés depuis leur dernière remise à zéro : comparez donc des relevés pris dans les mêmes conditions. Un ANALYZE manuel reste utile après un import massif ; le reste du temps, l'autovacuum de Postgres s'en charge.

Quelles sauvegardes et comment restaurer ?

• Sauvegardes quotidiennes automatiques sur Pro (7 jours accessibles), Team (14 jours) et Enterprise (jusqu'à 30 jours)⁹.
• Point-in-Time Recovery en add-on sur les plans payants, avec au minimum une instance de calcul Small, pour restaurer à la seconde près⁹ ; tarif affiché : 100 $ par mois par tranche de 7 jours de rétention⁸.
• Les sauvegardes de la base ne contiennent pas les fichiers de Storage, seulement leurs métadonnées : restaurer une ancienne sauvegarde ne ramène pas les fichiers supprimés depuis⁹.
• La restauration rend le projet inaccessible pendant l'opération, d'autant plus longtemps que la base est grosse : prévoyez une fenêtre de maintenance⁹.

Pour une copie hors site (indispensable sur le plan Free), Supabase recommande supabase db dump plutôt qu'un pg_dump brut, car la commande exclut les schémas gérés par Supabase²⁹ :

supabase db dump --db-url "$DB_URL" -f roles.sql --role-only
supabase db dump --db-url "$DB_URL" -f schema.sql
supabase db dump --db-url "$DB_URL" -f data.sql --use-copy --data-only

Un Makefile pour ne rien oublier

setup:
  supabase start
  supabase db reset
  npm run gen:types

push-staging:
  supabase link --project-ref $${STAGING_REF}
  supabase db push
  supabase functions deploy --project-ref $${STAGING_REF}

push-prod:
  @read -p "Déployer en PRODUCTION ? (yes/no) : " confirm && [ "$$confirm" = "yes" ]
  supabase link --project-ref $${PROD_REF}
  supabase db push --dry-run
  supabase db push
  supabase functions deploy --project-ref $${PROD_REF}

Si vous préférez déléguer l'architecture et l'automatisation de votre backend, c'est le rôle de notre agence d'automatisation et d'IA.