Sauvegarde Supabase gratuite avec une GitHub Action, et le piège

Votre projet Supabase est sur le plan gratuit, donc rien n'est copié nulle part, ou il est sur Pro et chaque copie qu'il prend vit à l'intérieur du compte que vous avez peur de perdre. Dans un fil de discussion sur ce sujet précis, quelqu'un a dit que la réponse était une GitHub Action de sauvegarde Supabase : un petit fichier dans un dépôt, qui exporte votre base chaque nuit et ne coûte rien.

Le conseil était bon. Supabase publie lui-même le workflow, et pour beaucoup d'apps c'est ce qu'il faut mettre en place cette semaine. Voici ce que ces fils laissent de côté : cela ne coûte pas d'argent, et cela a quand même un prix. Chaque exécution télécharge toute votre base de données, et Supabase mesure ce téléchargement.

Voyez-le comme la data de votre forfait mobile. Votre plan vient avec un quota mensuel, tout ce que fait votre app puise dedans, et une sauvegarde est un gros téléchargement sur le même forfait. Sur le plan gratuit, une copie nocturne d'une base proche de sa taille maximale consomme le quota de tout le mois en une dizaine de jours. Cela, plus une connection string que GitHub ne peut pas joindre, sont les deux choses entre vous et une sauvegarde qui fonctionne, et ni l'une ni l'autre ne figure sur la page de Supabase.

Peut-on sauvegarder Supabase gratuitement avec une GitHub Action ?

Oui, et Supabase documente comment. Sa page sur les sauvegardes automatiques avec GitHub Actions donne un workflow qui installe la CLI Supabase, exporte vos rôles, votre schéma et vos données dans trois fichiers, et les commite dans le dépôt selon un horaire.

GitHub ne vous facture rien non plus, dans certaines limites. Un dépôt privé sur GitHub Free reçoit 2 000 minutes Actions par mois, et un dump nocturne d'une petite base en consomme une petite partie.

Ce que vous obtenez, c'est une copie qui quitte Supabase chaque nuit et atterrit sur les serveurs d'une autre entreprise. C'est précisément ce que les sauvegardes de Supabase ne peuvent pas vous donner, car les copies quotidiennes d'un plan payant restent dans le compte qu'elles protègent.

C'est la bonne réponse quand trois conditions sont réunies. Votre app vit déjà dans un dépôt GitHub, ce qui est le cas si vous avez activé la synchronisation GitHub dans Lovable ou un builder du même genre. Modifier un fichier YAML ne vous inquiète pas. Et votre base est petite par rapport au quota d'egress de votre plan. Les deux premières, vous les connaissez déjà. La troisième relève de l'arithmétique, et elle a sa propre section plus bas.

Le workflow, avec l'horaire et le secret

Enregistrez ceci sous .github/workflows/supabase-backup.yml dans un dépôt privé qui ne contient rien d'autre :

name: supabase-backup

on:
  schedule:
    - cron: '17 3 * * *' # tous les jours à 03:17 UTC
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      SUPABASE_DB_URL: ${{ secrets.SUPABASE_DB_URL }}
    steps:
      - uses: actions/checkout@v7
      - uses: supabase/setup-cli@v3
        with:
          version: latest
      - name: Back up roles
        run: supabase db dump --db-url "$SUPABASE_DB_URL" -f roles.sql --role-only
      - name: Back up schema
        run: supabase db dump --db-url "$SUPABASE_DB_URL" -f schema.sql
      - name: Back up data
        run: >
          supabase db dump --db-url "$SUPABASE_DB_URL" -f data.sql --use-copy --data-only
          -x "storage.buckets_vectors" -x "storage.vector_indexes"
      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: Supabase backup

C'est le workflow de Supabase avec trois changements.

• Il s'exécute selon l'horaire et quand vous appuyez sur le bouton, et jamais autrement. La version de Supabase s'exécute aussi à chaque push et à chaque pull request sur main. Chaque exécution est un téléchargement complet de votre base, donc dans un dépôt qui contient aussi votre app, chaque changement livré coûterait l'équivalent d'une sauvegarde en quota.
• Il s'exécute à 03:17, en dehors de l'heure pile. GitHub indique que les exécutions planifiées peuvent être retardées au début de chaque heure, et qu'en cas de charge suffisante certaines tâches en file d'attente sont abandonnées. L'exemple de Supabase utilise 0 0 * * *, qui tombe pile sur l'heure. Les horaires sont en UTC sauf si vous ajoutez un timezone, et n'importe quelle minute autre que 0 convient.
• La ligne des données reprend le guide de sauvegarde et de restauration actuel de Supabase, qui ajoute deux exclusions -x absentes de la page du workflow. Les fichiers que vous gardez sont alors ceux pour lesquels les instructions de restauration de Supabase sont écrites.

Ensuite, le secret. Dans le dépôt, ouvrez Settings, puis Secrets and variables, puis Actions, et ajoutez un secret de dépôt nommé SUPABASE_DB_URL. Ce qu'on y met décide si tout cela fonctionne, alors il a la section suivante pour lui seul.

Une fois qu'il est enregistré, lancez le workflow à la main depuis l'onglet Actions, pour que la première exécution ait lieu sous vos yeux. workflow_dispatch est la ligne qui vous donne le bouton Run workflow.

Quelle connection string mettre dans le secret ?

La chaîne du Session pooler, depuis le bouton Connect en haut de votre projet Supabase. Prenez-la même si la page du workflow de Supabase montre la connexion directe dans son exemple.

La raison, c'est IPv6, le type d'adresse internet le plus récent. La connexion directe de Supabase, l'hôte qui commence par db. et finit par supabase.co, utilise IPv6 par défaut, et la même page range GitHub Actions parmi les services qui n'acceptent que l'IPv4. Le runner reçoit une adresse vers laquelle il n'a aucune route, et le premier dump échoue avant d'avoir écrit un seul octet. L'erreur dit que le nom d'hôte n'a pas pu être traduit, ou que le réseau est injoignable, souvent avec une longue adresse pleine de deux-points à côté. Cette adresse, c'est l'adresse IPv6. On dirait un mauvais mot de passe ou une base en panne, et la vraie cause est un réseau sur lequel le runner ne se trouve pas.

Le guide de sauvegarde et de restauration de Supabase dit d'utiliser par défaut la chaîne du Session pooler, et la directe seulement si votre réseau prend en charge IPv6 ou si vous payez l'option IPv4. Vous reconnaîtrez la chaîne du pooler à trois choses : son nom d'utilisateur est postgres. suivi de la référence de votre projet, son hôte se termine par pooler.supabase.com, et son port est 5432.

Le mot de passe qu'elle contient est celui de votre base de données, choisi à la création du projet, et pas une clé d'API. Si personne ne l'a noté, Supabase vous laisse le réinitialiser dans Database Settings ; tout ce qui se connecte avec l'ancien cesse alors de fonctionner jusqu'à ce que vous lui donniez le nouveau.

Cette chaîne peut lire et modifier chaque ligne de votre base. Elle vit dans le secret et nulle part ailleurs : jamais dans le fichier du workflow, jamais dans un message de commit, et jamais collée dans un assistant IA avec l'erreur sur laquelle vous vouliez l'interroger.

Une sauvegarde Supabase compte-t-elle dans mon egress ?

Oui, en entier. Supabase compte comme egress, c'est-à-dire comme trafic sortant, les données que n'importe lequel de ses services envoie vers l'extérieur, et un dump passé par le pooler est classé en Shared Pooler Egress, dans le même quota que votre trafic d'API, vos téléchargements de fichiers et tout ce que votre app sert par ailleurs.

Revenons au forfait mobile. Le quota se remet à zéro à chaque mois de facturation, chaque service utilisé par votre app puise dedans, et une sauvegarde est un gros téléchargement de plus. C'est aussi un forfait famille : Supabase applique le quota à toute votre organisation, donc tous les projets qu'elle contient partagent le même quota.

Le 26 septembre 2026, la page des tarifs de Supabase donnait au plan gratuit 5 Go d'egress par mois et une limite de 500 Mo pour la base de chaque projet, et au plan Pro 250 Go d'egress. Le plan gratuit a aussi 5 Go de cached egress, qui couvrent les fichiers servis depuis le CDN de Supabase, et une sauvegarde n'y touche jamais. Les autres limites du plan gratuit, et ce que fait chacune quand vous la franchissez, ont leur propre article.

Dépasser le quota sur le plan gratuit ne produit pas de facture. Supabase vous prévient et vous accorde un délai de grâce, et si vous continuez à le dépasser, il restreint chaque projet de l'organisation. Selon Supabase, cela peut vouloir dire des requêtes d'API refusées avec une erreur 402, une base passée en lecture seule ou des projets mis en pause. Pour une app qui a des clients, c'est une panne déclenchée par votre sauvegarde.

C'est vrai de toute sauvegarde qui sort de Supabase, y compris celle que nous vendons. Une copie gardée hors du compte doit être téléchargée pour y arriver.

À quelle fréquence la sauvegarde doit-elle tourner ?

Aussi souvent que votre quota peut le payer, et cela se résume à une seule multiplication : la taille de votre base, fois le nombre d'exécutions dans le mois.

Supabase affiche la taille de votre base dans le rapport Database, sous Observability dans votre projet. Un dump ne fait pas exactement cette taille. Il laisse de côté les index, reconstruits à partir de leur définition, et il écrit chaque valeur sous forme de texte. C'est assez proche pour planifier, et c'est le chiffre que vous pouvez consulter.

Un mois compte environ 4,3 semaines, d'où viennent les deux dernières colonnes.

Sur le plan gratuit, les deux chiffres quotidiens du bas dépensent plus que le quota de tout le mois avant que votre app ait répondu à une seule requête. Un horaire quotidien consomme les 5 Go entiers vers 160 Mo, et le trafic de votre app sort du même quota, alors regardez l'egress du mois dernier sur la page Usage de votre organisation avant de choisir. L'hebdomadaire tient à toutes les tailles que le plan gratuit autorise.

La ligne de cron est la seule chose que vous changez :

17 3 * * *      tous les jours à 03:17 UTC
17 3 * * 1,4    le lundi et le jeudi
17 3 * * 0      le dimanche

Sur Pro, l'arithmétique ne compte presque plus. 250 Go par mois paient un dump quotidien d'un projet jusqu'à environ 8 Go, ce qui est l'espace disque que le plan Pro inclut par projet.

Pourquoi mon workflow échoue-t-il avec une erreur de version de pg_dump ?

Parce que le pg_dump qu'il a lancé est plus ancien que votre base. Cela n'arrive qu'à un workflow qui appelle pg_dump directement plutôt que par la CLI Supabase. La CLI apporte son propre pg_dump, et c'est l'une des raisons pour lesquelles le workflow ci-dessus l'utilise.

Le runner ubuntu-latest de GitHub arrive avec PostgreSQL 16 installé. Les projets Supabase peuvent tourner sous Postgres 17, et Postgres documente que pg_dumpn'exporte pas depuis un serveur d'une version majeure plus récente que la sienne, et préfère refuser plutôt que risquer un fichier défectueux. L'exécution s'arrête sur :

pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 17.…; pg_dump version: 16.…

La version de votre projet se trouve sous Project Settings, puis General, si vous voulez la vérifier. Vos identifiants n'y sont pour rien.

La correction tient en deux étapes. Ajoutez le dépôt de paquets de PostgreSQL lui-même pour que le runner puisse installer le client en version 17, puis appelez ce client par son chemin complet :

- name: Install the Postgres 17 client
  run: |
    sudo apt-get install -y postgresql-common
    sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
    sudo apt-get install -y postgresql-client-17
- name: Back up
  run: /usr/lib/postgresql/17/bin/pg_dump "$SUPABASE_DB_URL" …

Gardez après la connection string les arguments que vous aviez déjà. Le chemin complet compte : sur Ubuntu, le pg_dump tout court est un intermédiaire qui choisit une version pour vous, et le runner a déjà une installation de PostgreSQL 16 à lui proposer.

Le pg_dump de la CLI a lui aussi une version, et elle ne vient pas de votre projet. Sans supabase/config.toml à côté du workflow, ce qui est le cas dans un dépôt qui ne contient rien d'autre, la CLI prend pg_dump 17. Sur un projet encore en Postgres 15, le data.sql qu'elle écrit contient alors SET transaction_timeout = 0, un réglage que Postgres 15 ne connaît pas, et le rejeu s'arrête sur cette ligne dans n'importe quelle base Postgres 15, y compris le projet d'où vient le fichier. Nous l'avons reproduit le 4 octobre 2026 avec pg_dump 17.11 et Postgres 15.19. Si votre projet est en 15, ajoutez une ligne au bloc env du job pour que la CLI utilise le pg_dump correspondant :

env:
  SUPABASE_DB_URL: ${{ secrets.SUPABASE_DB_URL }}
  SUPABASE_DB_MAJOR_VERSION: '15'

La sauvegarde elle-même se termine sans erreur dans les deux cas, donc sans cette ligne l'écart n'apparaît que le jour où le fichier est rejoué.

Puis-je commiter la sauvegarde dans mon dépôt ?

Dans un dépôt privé, oui. C'est ce que fait le workflow de Supabase, et sa page dit deux fois de ne jamais sauvegarder vos données dans un dépôt public.

Trois choses sur un dépôt comme lieu de vie d'une base de données, dont aucune ne figure sur cette page :

• Quiconque peut lire le dépôt peut lire vos utilisateurs. data.sql contient chaque ligne : adresses e-mail, noms, tout ce que gardent vos tables, et vos comptes aussi. C'est pour cela que le workflow a son propre dépôt, avec personne d'autre dessus, et pas celui qui contient le code de votre app, que votre builder synchronise peut-être et où un freelance sera peut-être un jour invité.
• La copie de chaque nuit reste dans l'historique. Git garde chaque version de chaque fichier. Quand une personne de votre clientèle vous demande de supprimer son compte, sa ligne reste dans chaque commit antérieur de ce dépôt tant que vous n'avez pas réécrit son historique.
• Tout s'arrête à 100 Mio. GitHub avertit au-delà de 50 Mio et bloque les fichiers de plus de 100 Mio, et la même page dit que Git n'est pas conçu pour gérer de gros fichiers SQL. La nuit où data.sql franchit cette limite, l'étape de commit échoue, et chaque exécution suivante échoue de la même manière.

Quand vous approchez de la limite, le même workflow peut envoyer les trois fichiers dans un bucket de stockage qui vous appartient au lieu de les commiter. Ou c'est le moment où le faire vous-même a cessé d'être bon marché, et c'est là que commence la dernière section.

Qu'est-ce que le workflow ne copie pas ?

Vos fichiers envoyés. Supabase Storage garde chaque fichier hors de la base de données et une ligne qui le décrit à l'intérieur, donc le dump emporte la ligne et pas l'image. Sauvegarder Storage est un travail à part, quelle que soit la méthode.

Vos utilisateurs, eux, y sont. Le dump des données parcourt le schéma auth où vivent vos comptes, et chercher auth.users dans data.sql vous les montre. Le projet autour de la base, en revanche, n'y est pas : Edge Functions, réglages des fournisseurs d'authentification, clés d'API et secrets relèvent de la configuration et non des données, et la liste de ce qu'aucune des deux copies ne contient est celle à lire avant d'en avoir besoin.

Une exécution verte veut-elle dire que la sauvegarde a marché ?

Elle veut dire que la tâche s'est terminée sans erreur, ce qui est une affirmation plus modeste. Trois résultats très différents finissent par la même coche verte :

1. Un bon dump du bon projet.
2. Un dump du mauvais projet, parce que le secret contient la chaîne d'une copie de staging.
3. Un dump sans aucune ligne, parce que quelqu'un a modifié la ligne des données et que --data-only a disparu, ce qui la retransforme en dump du schéma.

Un résultat ne laisse aucune trace. Une exécution planifiée que GitHub abandonne sous la charge n'apparaît pas comme un échec, puisqu'il n'y a aucune exécution pour échouer. Et quand une exécution échoue bel et bien, GitHub envoie la notification à la personne qui a modifié la ligne de cron en dernier. Si un freelance a mis cela en place pour vous, l'e-mail sur votre sauvegarde arrive dans sa boîte.

Seule une restauration les distingue. Rejouez les trois fichiers dans un projet Supabase jetable ou en local, comparez le nombre de lignes des tables qui comptent pour vous avec celles de la vraie base, et connectez-vous en tant que vrai utilisateur. Comment restaurer une sauvegarde Supabase donne les commandes, dans l'ordre indiqué par Supabase. Faites-le une fois maintenant, puis à chaque modification du workflow.

Vous pouvez aussi confier la restauration et le comptage à chaque run. Nous avons publié une version de ce workflow sous forme de GitHub Action open source, Reeve-page/supabase-backup-action. Elle réalise les trois mêmes dumps, garde la copie comme artefact du workflow ou dans un bucket S3 ou R2, puis la rejoue dans une base Supabase jetable sur le runner et compare le nombre de lignes de chaque table avec le fichier. Le run ne passe au vert que si chaque table est revenue avec les lignes que contient le fichier :

- uses: Reeve-page/supabase-backup-action@v1
  with:
    db-url: ${{ secrets.SUPABASE_DB_URL }}

Elle est gratuite et sous licence MIT. Chaque run télécharge toujours toute la base, donc le calcul d'egress plus haut s'applique tel quel, et la connexion reste à tester par vous.

Quand arrêter de le faire moi-même ?

Quand l'arithmétique ne tient plus, quand le fichier devient trop gros pour le dépôt, ou quand personne ne restaure les copies. Une seule de ces raisons suffit.

• Votre base a dépassé le quota gratuit. Pro porte l'egress à 250 Go et ajoute les sauvegardes quotidiennes de Supabase, conservées sept jours, qui se restaurent d'un bouton. Laissez le workflow tourner à côté, car ces copies vivent dans le compte.
• data.sql approche des 100 Mio. Le déplacer vers un bucket, c'est plus de YAML, et plus de choses que quelqu'un doit maintenir en état de marche.
• Personne n'a jamais restauré une copie. Le workflow continuera d'écrire des fichiers, qu'ils s'ouvrent ou non.
• Vos utilisateurs envoient des fichiers. Le workflow ne les atteint pas, et la tâche qui les atteint est une deuxième tâche à maintenir en vie.

Où Reeve Care intervient

Care prend la copie selon un horaire, la garde hors de votre compte Supabase et vérifie chaque copie avant qu'elle compte.

• Chaque jour avec Care, et plus souvent avec les plans au-dessus, sans rien dans votre dépôt et sans connection string dans une CI.
• Relue et comptée. Chaque copie est ouverte et comptée par rapport à ce qui y est entré, et la date affichée dans votre tableau de bord est celle de la dernière copie qui a passé cette vérification, jamais celle de la dernière exécution.
• Vos comptes sont dedans, et vos fichiers envoyés suivent dès que vous connectez un accès Storage.
• Restaurer, c'est un bouton, et une copie de l'état actuel est prise avant que quoi que ce soit ne soit remplacé.
• Chaque copie se télécharge en zip avec schema.sql, data.sql et roles.sql, les trois mêmes fichiers que ce workflow, plus le nombre de lignes de chaque table.

Care garde une copie de votre base Supabase. La copie, la vérification et la restauration sont dessinées étape par étape sur la page des sauvegardes Supabase, et ce que comprend chaque plan est sur la page des tarifs.

Ce qu'il faut faire cette semaine

Avant de fermer cet onglet, ouvrez dans Supabase la page Usage de votre organisation et lisez l'egress du mois dernier. Ce chiffre, à côté de la taille de votre base, choisit votre ligne de cron. Et si vous comparez encore la voie gratuite aux voies payantes, les quatre types d'outils de sauvegarde Supabase sont comparés côte à côte.