Distribuzione
Migrazioni senza tempi di inattività, rollback atomico, CI/CD tramite GitHub Azioni / GitLab / CLI e rami del database: una copia di un progetto per testare una migrazione o una policy prima della produzione.
Tre superfici di distribuzione#
Un progetto Aurabase espone tre superfici da distribuire: Postgres schema (migrazioni SQL con versione), funzioni edge (WASM + cron + job), policy e segreti (RLS, env vars, app OAuth). Ciascuno si spinge in modo indipendente tramite aura CLI.
La CLI (aura) è un singolo binario, installabile anche con npm install -g @aurabase/cli e supporta l'esecuzione a secco, i prompt di conferma e l'anteprima delle differenze. Compatibile con Linux/macOS/Windows.
Sviluppo, anteprima, produzione#
Per impostazione predefinita, un progetto ha due ambienti: dev (locale, Kubernetes) e prod (cloud). Per provare una modifica su una copia dei tuoi dati prima della produzione, crea un ramo del database branch di database.
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 con versione, rollback atomico#
Le migrazioni vivono in aurabase/migrations. Un file per modifica, timestamp nel prefisso. La CLI applica le migrazioni mancanti al progetto collegato; rigenera i tuoi tipi TypeScript con npx @aurabase/gen dopo una modifica.
# Crea una nuova migrazione
aura db migration new add_devices_table
# → aurabase/migrations/20260415120000_add_devices_table.sql
# Scopri quali migrazioni sono applicate o in sospeso, quindi applicale al progetto collegato
aura db status
aura db push
# Rigenera i tipi TypeScript
npx @aurabase/gen --out src/aurabase.types.ts
# Elenca le migrazioni applicate
aura db migration list
Migrazioni senza tempi di inattività. Segui le regole: aggiungi prima la colonna nullable, il backfill separato, per ultimo il vincolo NOT NULL. La CLI non verifica la compatibilità con le versioni precedenti: rivedi le istruzioni distruttive (drop column, alter column … type) prima di aura db push.
Rami del database#
Un ramo è un nuovo progetto clonato da un progetto PostgreSQL esistente: il suo schema, le policy di sicurezza a livello di riga, le funzioni, i trigger, le visualizzazioni e (a meno che tu non richieda solo lo schema) le sue righe. Ha il proprio URL, chiavi API e database, quindi puoi eseguire una migrazione, testare una policy o indirizzarvi una distribuzione in anteprima senza toccare l'origine. I rami vengono eliminati automaticamente al termine della loro vita.
# Dal progetto collegato (aura link), 72 ore per impostazione predefinita
aura branch create feat/new-checkout
# Da un altro progetto, conservato 7 giorni
aura branch create pr-142 --from my-app --ttl 7d
# Solo schema: nessuna riga viene copiata, le sequenze ricominciano da capo
aura branch create schema-test --no-data
aura branch list # i rami del progetto collegato
aura branch list --all # ogni ramo dell'organizzazione
aura branch delete feat/new-checkout
aura branch create attende che il ramo sia pronto, quindi stampa il suo URL e le sue chiavi API, mostrato solo una volta come quelle di aura projects create (--json le stampa per gli script). Utilizzare --no-wait per tornare subito e seguirlo con aura branch list. Un ramo è un progetto: collega una cartella ad esso con aura link --project-id <id> ed esegui aura db push lì per provare una migrazione.
Un ramo è una copia effettuata al momento della creazione, non una replica live e non un clone copy-on-write: nulla ritorna all'origine o da essa successivamente. La piattaforma legge l'origine in un'unica istantanea coerente e copia le righe nel database della filiale, quindi il tempo è proporzionale ai dati. Nello stack di test locale, una tabella da 333 MB con 350.000 righe è stata clonata in 14 secondi. Una migrazione che funziona sul branch viene poi applicata alla produzione con il solito aura db push.
Limiti, per intero#
| Chi può creare | Membri con il ruolo developer o più, da un progetto PostgreSQL attivo e non ibernato. Un progetto MongoDB viene rifiutato. |
| Diramazione di un ramo | Rifiutato: crea il ramo dal suo progetto principale. |
| Nome | Lettere, cifre, ., _, - e /, fino a 63 caratteri, univoci per progetto tra i rami attivi (senza distinzione tra maiuscole e minuscole). |
| Tempo di vivere | 72 ore per impostazione predefinita, da 1 ora a 30 giorni ( da --ttl 1h a --ttl 30d). Il ramo scaduto e il relativo database vengono cancellati automaticamente, entro circa un minuto dalla scadenza. Puoi eliminarlo prima. |
| Limite del piano | Un ramo non conta ai fini del limite del progetto (max_projects); ha il proprio limite di filiali attive per organizzazione (max_branches): 1 su Free, 10 su Pro, 25 su Team. Oltrepassandolo, la creazione viene rifiutata con BRANCH_LIMIT_REACHED. Un ramo fallito non conta. Vedi limiti. |
| Dimensione dati | Le righe vengono trasmesse in streaming, non mantenute in memoria, quindi non esiste un limite massimo di 32 MiB. La clonazione viene rifiutata, in pochi secondi, quando le tabelle contengono più del limite del deploy (2 GiB per impostazione predefinita, BRANCH_CLONE_MAX_BYTES quando si ospita Aurabase): il messaggio fornisce la dimensione e suggerisce --no-data. Anche un clone si ferma dopo 30 minuti. |
Ciò che non viene clonato#
- Clonato: tabelle e relative righe, tipi di colonna, valori predefiniti, colonne di identità, sequenze e relativo valore corrente, vincoli, indici, sicurezza a livello di riga (abilitata, forzata, policy), funzioni e procedure SQL, trigger, viste e viste materializzate, tipi di enumerazione e privilegi su tutti essi.
- Non clonato: utenti di autenticazione, sessioni e impostazioni di autenticazione; contenitori e oggetti di archiviazione; funzioni edge, segreti, variabili d'ambiente e lavori cron; impostazioni delle tabelle in tempo reale (riattivarle sul ramo); commenti di tabelle e colonne, incluse le direttive
@graphql; privilegi a livello di colonna; l'attivazione di pg_graphql (aura projects graphql-enablesul ramo). Gli oggetti sono di proprietà del ruolo di amministratore del ramo. - Rifiutato (il ramo sarebbe incompleto): tabelle partizionate ed ereditate, tabelle esterne, domini, tipi compositi e di intervallo, funzioni aggregate, regole di riscrittura, chiavi esterne che puntano a un altro schema ed estensioni diverse da quelle installate dalla piattaforma in ogni progetto.
Viene creato un ramo dallo schema mentre viene letto subito prima della copia. Non modificare lo schema dell'origine (aura db push, DDL) durante la creazione di un ramo.
Quando la creazione fallisce#
Niente è lasciato indietro. La copia viene eseguita in un'unica transazione sul database della filiale; ad ogni fallimento viene effettuato il rollback, il progetto del ramo viene cancellato, e aura branch create stampa il motivo (ad esempio l'oggetto che non può essere clonato). Il ramo fallito rimane visibile in aura branch list per 24 ore con il suo messaggio e il suo nome è nuovamente libero. Se il servizio database si riavvia durante una copia, il ramo viene dichiarato fallito ed eliminato dopo 45 minuti.
Tre integrazioni pronte#
La CLI funziona con qualsiasi CI. Ecco le ricette dei tre più comuni.
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 # o scarica il binario dalla pagina di rilascio
- run: aura login --token ${{ secrets.AURA_PAT }} # Token di accesso personale aura_pat_*
- run: aura link ${{ vars.AURA_PROJECT_ID }}
- run: aura db push
- run: aura deploy functions
Collega un progetto per ambiente (un progetto di gestione temporanea e un progetto di produzione) ed esegui la stessa pipeline su ciascuno. Non è presente alcun flag --env: la destinazione è il progetto a cui è collegata la cartella.
Atomico, tramite migrazione verso il basso#
Accanto a ciascuna migrazione 20260415_xxx.sql può essere presente un file 20260415_xxx.down.sql. aura db migration down [n] esegue le .down.sql delle ultime migrazioni applicate n, iniziando dalla più recente, e le rimuove dalla cronologia; il comando controlla la risposta del server e fallisce se non è stato ripristinato nulla. Una migrazione senza .down.sql viene solo rimossa dalla cronologia e la CLI lo dice.
# Ripristina l'ultima migrazione applicata (esegue il suo .down.sql)
aura db migration down
# Ripristina gli ultimi tre
aura db migration down 3
# Correggi la cronologia senza toccare lo schema (una migrazione applicata manualmente, una migrazione non riuscita)
aura db migration repair 20260415120000_add_devices_table.sql --applied
# Una migrazione non riuscita viene annullata nella propria transazione: nulla da ripristinare.
# Il ripristino point-in-time di un intero database avviene tramite backup (aura db backup Restore <id> --yes)
Ripristino point-in-time non dispone ancora di un comando self-service. Per un ripristino guidato da solo, utilizza gli snapshot di aura db backup create / aura db backup restore <id> --yes; il ripristino sovrascrive il database, quindi esegui prima un nuovo backup.