Branches

Um branch é um ponteiro para um Log Sequence Number (LSN) no storage do projeto. Criar um é um insert de linha O(1); ele não copia dados. Branches divergem conforme você escreve neles, e apenas o delta é armazenado.

O modelo

Todo projeto tem um branch main desde a criação. A partir de main (ou de qualquer branch existente) você pode bifurcar um novo branch:

• No HEAD — o novo branch começa a partir do LSN atual do pai.
• Em um LSN específico — o novo branch começa a partir de um LSN histórico dentro da janela de retenção de WAL do pai. Este é o caso de "viagem no tempo": você pode bifurcar a partir de um ponto no passado desde que o WAL ainda esteja retido.

Leituras em um branch caem para as páginas do pai até que o branch divirja. Escritas registram apenas o delta. O resultado:

• Um projeto de 100 GB com dez branches pequenos é cobrado como ~100 GB no total.
• Criar um branch leva menos de um segundo.
• Branches são descartáveis. Rode uma migração destrutiva, jogue o branch fora, o pai fica intocado.

Nomenclatura

Nomes de branch são rótulos visíveis ao usuário, com escopo no projeto pai. As restrições coincidem com as de nomes de projeto:

• 1–63 caracteres.
• ^[a-zA-Z][a-zA-Z0-9_-]*$.
• Único dentro do projeto.

O id interno do branch (br_<24 hex>) é a referência estável. Use o id, não o nome, ao criar scripts contra a API; nomes podem ser renomeados.

Máquina de estados

Um branch transita por:

creating → ready → deleting → deleted

• creating — o control plane está registrando o branch na camada de storage. Tipicamente menos de um segundo; mais longo se o storage estiver sob carga.
• ready — o branch pode ser anexado a endpoints e aceitar escritas.
• deleting — cascata em andamento: cada endpoint neste branch está sendo parado e removido.
• deleted — terminal. A linha é retida para auditabilidade por um curto período, depois é coletada como lixo.

A CLI mostra o estado atual de cada branch:

keon branches list --project <project-id>

Criar

keon branches create --project <project-id> --name my-feature --parent main

Para bifurcar em um LSN histórico, passe --parent-lsn <lsn>:

keon branches create \
  --project <project-id> \
  --name pre-migration \
  --parent main \
  --parent-lsn 0/1A2B3C4D

O LSN deve estar dentro da janela de retenção de WAL do projeto. Se ele já tiver sido compactado para além disso, a criação do branch falha.

Excluir

Excluir um branch faz cascata para cada endpoint anexado a ele:

1. Todos os endpoints no branch são parados e removidos.
2. O próprio branch é desmontado.
3. O storage é recuperado de forma assíncrona pela compactação do pageserver.

keon branches delete <branch-id>

Você não pode excluir o branch main de um projeto — exclua o projeto em vez disso. Você pode excluir qualquer outro branch mesmo que ele tenha filhos; nesse caso os filhos são reparentados ao pai do branch excluído no LSN da exclusão.

Reset e restauração

Na página de detalhes do branch no console, o menu de ações ⋯ expõe duas operações de re-fork em qualquer branch que não seja raiz:

• Reset para o pai — re-bifurca o branch no HEAD atual do seu pai. Toda escrita feita no branch desde o fork original é descartada. Endpoints no branch suspendem brevemente durante a troca.
• Restaurar para um ponto no tempo — re-bifurca o branch em um LSN escolhido ou um timestamp UTC (RFC 3339). Escritas após esse ponto são descartadas.

Ambas rodam de forma assíncrona: o console emite a requisição e o branch retorna a ready assim que o re-fork conclui. O branch raiz (main) não pode ser resetado — não há pai para o qual resetar.

Snapshots

Um snapshot fixa um LSN de ponto no tempo para que ele permaneça restaurável além do horizonte de retenção de WAL. Sem um snapshot, um alvo de restauração só é alcançável enquanto seu WAL ainda estiver retido; um snapshot mantém esse ponto endereçável indefinidamente.

A aba Snapshots na página de detalhes do branch lista os snapshots do branch e permite capturar um novo. Cada linha oferece:

• Restaurar — re-bifurca o branch no LSN fixado do snapshot.
• Excluir — remove o snapshot (o LSN subjacente deixa de estar fixado e pode ser recuperado pela compactação).

Relacionado

• Projetos — o que possui o branch.
• Endpoints — o que anexa a um branch para aceitar tráfego de clientes.
• Conceitos — a separação storage / compute que torna os branches gratuitos.