Branches

Une branche est un pointeur vers un Log Sequence Number (LSN) dans le stockage du projet. En créer une est une insertion de ligne en O(1) ; elle ne copie pas les données. Les branches divergent au fur et à mesure que vous y écrivez, et seul le delta est stocké.

Le modèle

Chaque projet a une branche main dès sa création. Depuis main (ou toute branche existante), vous pouvez forker une nouvelle branche :

• Au HEAD — la nouvelle branche démarre depuis le LSN courant du parent.
• À un LSN spécifique — la nouvelle branche démarre depuis un LSN historique dans la fenêtre de rétention du WAL du parent. C'est le cas du « voyage dans le temps » : vous pouvez brancher à partir d'un point du passé tant que le WAL est encore conservé.

Les lectures sur une branche retombent sur les pages du parent jusqu'à ce que la branche diverge. Les écritures n'enregistrent que le delta. Le résultat :

• Un projet de 100 Go avec dix petites branches est facturé environ 100 Go au total.
• Engendrer une branche prend moins d'une seconde.
• Les branches sont jetables. Lancez une migration destructrice, jetez la branche, le parent est intact.

Nommage

Les noms de branche sont des libellés visibles par l'utilisateur, limités au projet parent. Les contraintes correspondent aux noms de projet :

• 1 à 63 caractères.
• ^[a-zA-Z][a-zA-Z0-9_-]*$.
• Unique au sein du projet.

L'id interne de branche (br_<24 hex>) est la référence stable. Utilisez l'id, pas le nom, lorsque vous scriptez contre l'API ; les noms peuvent être renommés.

Machine à états

Une branche transite par :

creating → ready → deleting → deleted

• creating — le plan de contrôle enregistre la branche auprès de la couche de stockage. Généralement moins d'une seconde ; plus long si le stockage est sous charge.
• ready — la branche peut être attachée à des endpoints et accepter des écritures.
• deleting — cascade en cours : chaque endpoint sur cette branche est arrêté et supprimé.
• deleted — terminal. La ligne est conservée à des fins d'audit pendant une courte période, puis ramassée par le garbage collector.

La CLI affiche l'état courant de chaque branche :

keon branches list --project <project-id>

Créer

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

Pour brancher à un LSN historique, passez --parent-lsn <lsn> :

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

Le LSN doit se trouver dans la fenêtre de rétention du WAL du projet. S'il a été compacté au-delà, la création de la branche échoue.

Supprimer

Supprimer une branche cascade vers chaque endpoint qui y est attaché :

1. Tous les endpoints sur la branche sont arrêtés et supprimés.
2. La branche elle-même est démantelée.
3. Le stockage est récupéré de façon asynchrone par la compaction du pageserver.

keon branches delete <branch-id>

Vous ne pouvez pas supprimer la branche main d'un projet — supprimez le projet à la place. Vous pouvez supprimer toute autre branche même si elle a des enfants ; dans ce cas, les enfants sont rattachés au parent de la branche supprimée au LSN de suppression.

Réinitialiser et restaurer

Depuis la page de détail de la branche dans la console, le menu d'actions ⋯ expose deux opérations de re-fork sur toute branche non racine :

• Réinitialiser au parent — re-forke la branche au HEAD courant de son parent. Chaque écriture effectuée sur la branche depuis le fork original est abandonnée. Les endpoints de la branche se suspendent brièvement pendant le basculement.
• Restaurer à un instant donné — re-forke la branche à un LSN choisi ou à un horodatage UTC (RFC 3339). Les écritures postérieures à ce point sont abandonnées.

Les deux s'exécutent de façon asynchrone : la console émet la requête et la branche revient à ready une fois le re-fork effectué. La branche racine (main) ne peut pas être réinitialisée — il n'y a pas de parent vers lequel réinitialiser.

Snapshots

Un snapshot épingle un LSN à un instant donné pour qu'il reste restaurable au-delà de l'horizon de rétention du WAL. Sans snapshot, une cible de restauration n'est atteignable que tant que son WAL est encore conservé ; un snapshot maintient ce point adressable indéfiniment.

L'onglet Snapshots de la page de détail de la branche liste les snapshots de la branche et vous permet d'en capturer un nouveau. Chaque ligne propose :

• Restaurer — re-forke la branche au LSN épinglé du snapshot.
• Supprimer — supprime le snapshot (le LSN sous-jacent n'est plus épinglé et peut être récupéré par la compaction).

Liens connexes

• Projets — ce qui possède la branche.
• Endpoints — ce qui s'attache à une branche pour accepter le trafic client.
• Concepts — la séparation stockage / calcul qui rend les branches gratuites.