Ramas

Una rama es un puntero a un Número de Secuencia de Log (LSN) en el almacenamiento del proyecto. Crear una es una inserción de fila O(1); no copia datos. Las ramas divergen a medida que escribe en ellas, y solo se almacena el delta.

El modelo

Cada proyecto tiene una rama main desde su creación. Desde main (o cualquier rama existente) puede bifurcar una nueva rama:

• En HEAD — la nueva rama empieza desde el LSN actual del padre.
• En un LSN específico — la nueva rama empieza desde un LSN histórico dentro de la ventana de retención de WAL del padre. Este es el caso de "viaje en el tiempo": puede bifurcar desde un punto del pasado mientras el WAL aún se conserve.

Las lecturas en una rama recurren a las páginas del padre hasta que la rama diverge. Las escrituras registran solo el delta. El resultado:

• Un proyecto de 100 GB con diez ramas pequeñas se factura como ~100 GB en total.
• Crear una rama es subsegundo.
• Las ramas son desechables. Ejecute una migración destructiva, tire la rama, el padre queda intacto.

Nombres

Los nombres de rama son etiquetas visibles para el usuario, limitadas al proyecto padre. Las restricciones coinciden con las de los nombres de proyecto:

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

El id interno de la rama (br_<24 hex>) es la referencia estable. Use el id, no el nombre, al hacer scripting contra la API; los nombres pueden renombrarse.

Máquina de estados

Una rama transiciona por:

creating → ready → deleting → deleted

• creating — el plano de control está registrando la rama con la capa de almacenamiento. Normalmente subsegundo; más largo si el almacenamiento está bajo carga.
• ready — la rama puede adjuntarse a endpoints y aceptar escrituras.
• deleting — cascada en curso: cada endpoint en esta rama se está deteniendo y eliminando.
• deleted — terminal. La fila se conserva para auditabilidad durante un breve periodo, y luego se recolecta como basura.

La CLI muestra el estado actual de cada rama:

keon branches list --project <project-id>

Crear

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

Para bifurcar en un LSN histórico, pase --parent-lsn <lsn>:

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

El LSN debe estar dentro de la ventana de retención de WAL del proyecto. Si se ha compactado más allá, la creación de la rama falla.

Eliminar

Eliminar una rama hace cascada a cada endpoint adjunto a ella:

1. Todos los endpoints en la rama se detienen y eliminan.
2. La propia rama se desmonta.
3. El almacenamiento se reclama de forma asíncrona por la compactación del pageserver.

keon branches delete <branch-id>

No puede eliminar la rama main de un proyecto — elimine el proyecto en su lugar. Puede eliminar cualquier otra rama incluso si tiene hijos; en ese caso los hijos se reasignan al padre de la rama eliminada en el LSN de eliminación.

Restablecer y restaurar

Desde la página de detalle de la rama en la consola, el menú de acciones ⋯ expone dos operaciones de rebifurcación en cualquier rama no raíz:

• Restablecer al padre — rebifurca la rama en el HEAD actual de su padre. Cada escritura hecha en la rama desde la bifurcación original se descarta. Los endpoints en la rama se suspenden brevemente durante el intercambio.
• Restaurar a un punto en el tiempo — rebifurca la rama en un LSN elegido o una marca de tiempo UTC (RFC 3339). Las escrituras posteriores a ese punto se descartan.

Ambas se ejecutan de forma asíncrona: la consola emite la solicitud y la rama vuelve a ready una vez que la rebifurcación aterriza. La rama raíz (main) no puede restablecerse — no hay padre al que restablecer.

Instantáneas

Una instantánea fija un LSN en un punto en el tiempo para que siga siendo restaurable más allá del horizonte de retención de WAL. Sin una instantánea, un objetivo de restauración solo es alcanzable mientras su WAL aún se conserve; una instantánea mantiene ese punto direccionable indefinidamente.

La pestaña Instantáneas en la página de detalle de la rama lista las instantáneas de la rama y le permite capturar una nueva. Cada fila ofrece:

• Restaurar — rebifurca la rama en el LSN fijado de la instantánea.
• Eliminar — descarta la instantánea (el LSN subyacente ya no está fijado y puede ser reclamado por la compactación).

Relacionado

• Proyectos — lo que posee la rama.
• Endpoints — lo que se adjunta a una rama para aceptar tráfico de clientes.
• Conceptos — la separación almacenamiento / cómputo que hace que las ramas sean gratis.