Déploiement
Migrations zero-downtime, rollback atomique, CI/CD via GitHub Actions / GitLab / CLI, et branches de base de données : une copie d'un projet pour tester une migration ou une policy avant la production.
Trois surfaces de déploiement#
Un projet Aurabase expose trois surfaces à déployer : schéma Postgres (migrations SQL versionnées), edge functions (WASM + cron + jobs), policies et secrets (RLS, env vars, OAuth apps). Chacune se pousse indépendamment via aura CLI.
Le CLI (aura) est un binaire unique, aussi installable avec npm install -g @aurabase/cli, et supporte dry-run, confirm prompts, diff prévisualisation. Compatible Linux / macOS / Windows.
Dev, preview, prod#
Par défaut, un projet a deux environnements : dev (local, Kubernetes) et prod (cloud). Pour essayer un changement sur une copie de vos données avant la production, créez une branche de base de données.
LOCAL DEV
$ ./start.sh → full local stack (k3d)
$ aura dev → watch mode + types gen
BRANCH (copy of a project, deleted by its TTL)
$ aura branch create pr-142 --from my-app --ttl 3d
$ aura db push → on the branch project, to try the migration
$ aura branch delete pr-142
PRODUCTION
merge to main → CI run: aura db push
→ aura deploy functions
SQL versionné, rollback atomique#
Les migrations vivent dans aurabase/migrations. Un fichier par changement, timestamp en préfixe. Le CLI applique les migrations manquantes au projet lié ; régénérez vos types TypeScript avec npx @aurabase/gen après un changement.
# Create a new migration
aura db migration new add_devices_table
# → aurabase/migrations/20260415120000_add_devices_table.sql
# See which migrations are applied or pending, then apply them to the linked project
aura db status
aura db push
# Regenerate TypeScript types
npx @aurabase/gen --out src/aurabase.types.ts
# List applied migrations
aura db migration list
Zero-downtime migrations. Suivez les règles : ajout de colonne nullable d'abord, backfill séparé, constraint NOT NULL en dernier. Le CLI ne vérifie pas la rétrocompatibilité à votre place : relisez les instructions destructrices (drop column, alter column … type) avant aura db push.
Branches de base de données#
Une branche est un nouveau projet cloné à partir d'un projet PostgreSQL existant : son schéma, ses policies de sécurité au niveau des lignes (RLS), ses fonctions, ses triggers, ses vues et (sauf si vous demandez le schéma seul) ses lignes. Elle a sa propre URL, ses propres clés d'API et sa propre base : vous pouvez y jouer une migration, y tester une policy ou y brancher un déploiement de prévisualisation sans toucher à la source. Les branches sont supprimées automatiquement à la fin de leur durée de vie.
# À partir du projet lié (aura link), 72 heures par défaut
aura branch create feat/new-checkout
# À partir d'un autre projet, conservée 7 jours
aura branch create pr-142 --from my-app --ttl 7d
# Schéma seul : aucune ligne n'est copiée, les séquences repartent du début
aura branch create schema-test --no-data
aura branch list # les branches du projet lié
aura branch list --all # toutes les branches de l'organisation
aura branch delete feat/new-checkout
aura branch create attend que la branche soit prête, puis affiche son URL et ses clés d'API, montrées une seule fois comme celles de aura projects create (--json les imprime pour les scripts). --no-wait rend la main tout de suite ; suivez alors la branche avec aura branch list. Une branche est un projet : liez un dossier avec aura link --project-id <id> et lancez aura db push pour y essayer une migration.
Une branche est une copie faite à la création, pas une réplique vivante ni un clone copy-on-write : rien ne circule ensuite de la source vers la branche, ni l'inverse. La plateforme lit la source dans un instantané cohérent et copie les lignes dans la base de la branche ; la durée est donc proportionnelle aux données. Sur la pile de test locale, une table de 333 Mo et 350 000 lignes a été clonée en 14 secondes. Une migration qui passe sur la branche s'applique ensuite en production avec le aura db push habituel.
Les limites, en entier#
| Qui peut créer | Les membres de rôle developer ou supérieur, à partir d'un projet PostgreSQL actif et non en hibernation. Un projet MongoDB est refusé. |
| Brancher une branche | Refusé : créez la branche à partir de son projet parent. |
| Nom | Lettres, chiffres, ., _, - et /, 63 caractères au plus, unique par projet parmi les branches vivantes (sans distinction de casse). |
| Durée de vie | 72 heures par défaut, de 1 heure à 30 jours (--ttl 1h à --ttl 30d). La branche échue et sa base sont supprimées automatiquement, environ une minute au plus après l'échéance. Vous pouvez la supprimer plus tôt. |
| Limite du plan | Une branche ne compte pas dans votre limite de projets (max_projects) ; elle a sa propre limite de branches actives par organisation (max_branches) : 1 en Free, 10 en Pro, 25 en Team. Au-delà, la création est refusée avec BRANCH_LIMIT_REACHED. Une branche en échec ne compte pas. Voir les limites. |
| Taille des données | Les lignes sont transmises en flux, sans être gardées en mémoire : il n'y a pas de plafond de 32 Mio. Le clonage est refusé, en quelques secondes, quand les tables dépassent la limite du déploiement (2 Gio par défaut, BRANCH_CLONE_MAX_BYTES si vous hébergez Aurabase) : le message donne la taille et propose --no-data. Un clonage s'arrête aussi au bout de 30 minutes. |
Ce qui n'est pas cloné#
- Cloné : les tables et leurs lignes, les types de colonnes, les valeurs par défaut, les colonnes d'identité, les séquences et leur valeur courante, les contraintes, les index, la sécurité au niveau des lignes (activée, forcée, policies), les fonctions et procédures SQL, les triggers, les vues et vues matérialisées, les types enum, et les privilèges sur tout cela.
- Non cloné : les utilisateurs d'authentification, les sessions et les réglages d'auth ; les buckets et objets de stockage ; les fonctions edge, les secrets, les variables d'environnement et les tâches cron ; les réglages temps réel des tables (réactivez-les sur la branche) ; les commentaires de tables et de colonnes, y compris les directives
@graphql; les privilèges au niveau des colonnes ; l'activation de pg_graphql (aura projects graphql-enablesur la branche). Les objets appartiennent au rôle administrateur de la branche. - Refusé (la branche serait incomplète) : les tables partitionnées et héritées, les tables étrangères, les domaines, les types composites et d'intervalle, les fonctions d'agrégation, les règles de réécriture, les clés étrangères qui pointent vers un autre schéma, et les extensions autres que celles que la plateforme installe dans chaque projet.
Une branche est créée à partir du schéma tel qu'il est lu juste avant la copie. Ne modifiez pas le schéma de la source (aura db push, DDL) pendant la création d'une branche.
Quand la création échoue#
Rien ne reste derrière. La copie se fait dans une seule transaction sur la base de la branche ; au moindre échec elle est annulée, le projet de la branche est supprimé, et aura branch create affiche la raison (par exemple l'objet qui ne peut pas être cloné). La branche en échec reste visible dans aura branch list pendant 24 heures avec son message, et son nom est de nouveau libre. Si le service de base de données redémarre au milieu d'une copie, la branche est déclarée en échec et supprimée au bout de 45 minutes.
Trois intégrations prêtes#
Le CLI fonctionne avec n'importe quel CI. Voici les recettes pour les trois plus courants.
name: Deploy to Aurabase
on:
push: { branches: [main] }
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g @aurabase/cli # or download the binary from the release page
- run: aura login --token ${{ secrets.AURA_PAT }} # Personal Access Token aura_pat_*
- run: aura link ${{ vars.AURA_PROJECT_ID }}
- run: aura db push
- run: aura deploy functions
Liez un projet par environnement (un projet de préproduction et un projet de production) et lancez le même pipeline sur chacun. Il n'existe pas d'option --env : la cible est le projet auquel le dossier est lié.
Atomique, via down migration#
Chaque migration 20260415_xxx.sql peut avoir un fichier 20260415_xxx.down.sql à côté d'elle. aura db migration down [n] exécute le .down.sql des n dernières migrations appliquées, de la plus récente à la plus ancienne, puis les retire de l'historique ; la commande vérifie la réponse du serveur et échoue si rien n'a été annulé. Une migration sans .down.sql est seulement retirée de l'historique, et le CLI le dit.
# Annuler la dernière migration appliquée (exécute son .down.sql)
aura db migration down
# Annuler les trois dernières
aura db migration down 3
# Corriger l'historique sans toucher au schéma (migration appliquée à la main, migration en échec)
aura db migration repair 20260415120000_add_devices_table.sql --applied
# Une migration en échec est annulée dans sa propre transaction : rien à annuler.
# La restauration d'une base entière passe par les sauvegardes (aura db backup restore <id> --yes)
La récupération à un instant donné (PITR) n'a pas encore de commande en libre-service. Pour une restauration que vous pilotez vous-même, utilisez les snapshots de aura db backup create / aura db backup restore <id> --yes ; la restauration écrase la base, faites donc d'abord une sauvegarde fraîche.