Implantação
Migrações com tempo de inatividade zero, reversão atômica, CI/CD via GitHub Actions/GitLab/CLI e ramificações de banco de dados: uma cópia de um projeto para testar uma migração ou política antes da produção.
Três superfícies de implantação#
Um projeto Aurabase expõe três superfícies para implantação: Postgres esquema (migrações SQL versionadas), funções de borda (WASM + cron + jobs), políticas e segredos (RLS, env vars, OAuth aplicativos). Cada um se empurra de forma independente por meio da CLI aura.
A CLI (aura) é um binário único, também instalável com npm install -g @aurabase/cli, e suporta simulação, prompts de confirmação e visualização de diferenças. Compatível com Linux/macOS/Windows.
Desenvolvimento, visualização, produção#
Por padrão, um projeto possui dois ambientes: dev (local, Kubernetes) e prod (nuvem). Para tentar alterar uma cópia dos seus dados antes da produção, crie uma ramificação do banco de dados branches de banco de dados.
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 versionado, reversão atômica#
As migrações residem em aurabase/migrations. Um arquivo por alteração, carimbo de data/hora no prefixo. A CLI aplica as migrações ausentes ao projeto vinculado; gere novamente seus tipos TypeScript com npx @aurabase/gen após uma alteração.
# Crie uma nova migração
aura db migration new add_devices_table
# → aurabase/migrations/20260415120000_add_devices_table.sql
# Veja quais migrações estão aplicadas ou pendentes e aplique-as ao projeto vinculado
aura db status
aura db push
# Regenerar tipos TypeScript
npx @aurabase/gen --out src/aurabase.types.ts
# Listar migrações aplicadas
aura db migration list
Migrações com tempo de inatividade zero. Siga as regras: adicione a coluna anulável primeiro, o preenchimento separado e a restrição NOT NULL por último. A CLI não verifica a compatibilidade com versões anteriores para você: revise as instruções destrutivas (drop column, alter column … type) antes de aura db push.
Ramos de banco de dados#
Uma ramificação é um novo projeto clonado de um projeto PostgreSQL existente: seu esquema, políticas de segurança em nível de linha, funções, gatilhos, visualizações e (a menos que você solicite apenas o esquema) suas linhas. Ele tem seu próprio URL, chaves de API e banco de dados, para que você possa executar uma migração, testar uma política ou apontar uma implantação de visualização sem tocar na origem. As ramificações são excluídas automaticamente quando seu tempo de vida termina.
# Do projeto vinculado (aura link), 72 horas por padrão
aura branch create feat/new-checkout
# De outro projeto, mantido 7 dias
aura branch create pr-142 --from my-app --ttl 7d
# Somente esquema: nenhuma linha é copiada, as sequências são reiniciadas
aura branch create schema-test --no-data
aura branch list # os ramos do projeto vinculado
aura branch list --all # cada ramo da organização
aura branch delete feat/new-checkout
aura branch create espera até que o branch esteja pronto, então imprime sua URL e suas chaves de API, mostrado apenas uma vez como aqueles de aura projects create (--json imprime-os para scripts). Use --no-wait para retornar imediatamente e siga com aura branch list. Uma ramificação é um projeto: vincule uma pasta a ela com aura link --project-id <id> e execute aura db push lá para tentar uma migração.
Uma ramificação é uma cópia feita no momento da criação, não uma réplica ativa e não um clone de cópia na gravação: nada flui de volta para a fonte ou dela posteriormente. A plataforma lê a origem em um instantâneo consistente e copia as linhas no banco de dados da filial, de forma que o tempo seja proporcional aos dados. Na pilha de teste local, uma tabela de 333 MB com 350.000 linhas foi clonada em 14 segundos. Uma migração que funciona na filial é então aplicada à produção com o aura db push usual.
Limites, na íntegra#
| Quem pode criar | Membros com a função developer ou mais, de um projeto PostgreSQL que está ativo e não hibernado. Um projeto MongoDB é recusado. |
| Ramificando uma ramificação | Recusado: crie o branch a partir de seu projeto pai. |
| Nome | Letras, dígitos, ., _, - e /, até 63 caracteres, exclusivos por projeto entre as ramificações ativas (sem distinção entre maiúsculas e minúsculas). |
| Hora de viver | 72 horas por padrão, de 1 hora a 30 dias (--ttl 1h a --ttl 30d). A agência expirada e seu banco de dados são excluídos automaticamente, cerca de um minuto após o prazo. Você pode excluí-lo antes. |
| Limite do plano | Uma ramificação não conta no limite do seu projeto (max_projects); tem seu próprio limite de filiais ativas por organização (max_branches): 1 no Free, 10 no Pro, 25 no Team. Depois disso, a criação é recusada com BRANCH_LIMIT_REACHED. Uma ramificação com falha não conta. Consulte limites. |
| Tamanho dos dados | As linhas são transmitidas e não mantidas na memória, portanto não há limite de 32 MiB. A clonagem é recusada, em alguns segundos, quando as tabelas contêm mais que o limite da implantação (2 GiB por padrão, BRANCH_CLONE_MAX_BYTES quando você hospeda Aurabase): a mensagem fornece o tamanho e sugere --no-data. Um clone também para após 30 minutos. |
O que não é clonado#
- Clonado: tabelas e suas linhas, tipos de colunas, padrões, colunas de identidade, sequências e seus valores atuais, restrições, índices, segurança em nível de linha (ativada, forçada, políticas), funções e procedimentos SQL, gatilhos, visualizações e visualizações materializadas, tipos de enum e os privilégios em todos eles.
- Não clonado: usuários de autenticação, sessões e configurações de autenticação; baldes e objetos de armazenamento; funções de borda, segredos, variáveis de ambiente e cron jobs; configurações de tabela em tempo real (reativá-las na filial); comentários de tabelas e colunas, incluindo diretivas
@graphql; privilégios em nível de coluna; a ativação de pg_graphql (aura projects graphql-enablena filial). Os objetos pertencem à função administrativa da filial. - Recusou (a ramificação ficaria incompleta): tabelas particionadas e herdadas, tabelas estrangeiras, domínios, tipos compostos e de intervalo, funções agregadas, regras de reescrita, chaves estrangeiras que apontam para outro esquema e extensões diferentes daquelas que a plataforma instala em cada projeto.
Uma ramificação é criada a partir do esquema à medida que é lida antes da cópia. Não altere o esquema da origem (aura db push, DDL) enquanto uma ramificação estiver sendo criada.
Quando a criação falha#
Nada é deixado para trás. A cópia é executada em uma única transação no banco de dados da filial; em caso de falha, ele é revertido, o projeto branch é excluído e aura branch create imprime o motivo (por exemplo, o objeto que não pode ser clonado). A ramificação com falha permanece visível em aura branch list por 24 horas com sua mensagem e seu nome fica livre novamente. Se o serviço de banco de dados for reiniciado no meio de uma cópia, a ramificação será declarada com falha e excluída após 45 minutos.
Três integrações prontas#
A CLI funciona com qualquer CI. Aqui estão as receitas dos três mais comuns.
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 # ou baixe o binário da página de lançamento
- run: aura login --token ${{ secrets.AURA_PAT }} # Token de acesso pessoal aura_pat_*
- run: aura link ${{ vars.AURA_PROJECT_ID }}
- run: aura db push
- run: aura deploy functions
Vincule um projeto por ambiente (um projeto de preparo e um projeto de produção) e execute o mesmo pipeline em cada um. Não há sinalizador --env: o destino é o projeto ao qual a pasta está vinculada.
Atômico, via migração descendente#
Cada migração 20260415_xxx.sql pode ter um arquivo 20260415_xxx.down.sql próximo a ela. aura db migration down [n] executa o .down.sql das últimas migrações aplicadas n, as mais novas primeiro, e as remove do histórico; o comando verifica a resposta do servidor e falha se nada for revertido. Uma migração sem .down.sql só é removida do histórico, e a CLI diz isso.
# Reverter a última migração aplicada (executa seu .down.sql)
aura db migration down
# Reverter os três últimos
aura db migration down 3
# Corrija o histórico sem mexer no esquema (uma migração aplicada manualmente, uma que falhou)
aura db migration repair 20260415120000_add_devices_table.sql --applied
# Uma migração com falha é cancelada em sua própria transação: nada para reverter.
# A recuperação pontual de um banco de dados inteiro passa por backups (aura db backup restore <id> --yes)
Recuperação pontual ainda não possui comando de autoatendimento. Para uma restauração que você mesmo conduz, use os instantâneos de aura db backup create / aura db backup restore <id> --yes; a restauração substitui o banco de dados, portanto, faça primeiro um novo backup.