Branches

Copy-on-Write-Postgres-Branches in Kisenon — Fork-at-LSN, Lebenszyklus und Kaskade.

Ein Branch ist ein Zeiger auf eine Log Sequence Number (LSN) im Speicher des Projekts. Einen zu erstellen ist ein O(1)-Zeileneinfügen; es kopiert keine Daten. Branches divergieren, während Sie in sie schreiben, und nur das Delta wird gespeichert.

Das Modell

Jedes Projekt hat ab der Erstellung einen main-Branch. Von main (oder jedem bestehenden Branch) können Sie einen neuen Branch forken:

Bei HEAD — der neue Branch startet von der aktuellen LSN des Parents.
Bei einer bestimmten LSN — der neue Branch startet von einer historischen LSN innerhalb des WAL-Aufbewahrungsfensters des Parents. Dies ist der „Time-Travel"- Fall: Sie können von einem Punkt in der Vergangenheit forken, solange das WAL noch aufbewahrt wird.

Lesevorgänge auf einem Branch fallen auf die Pages des Parents zurück, bis der Branch divergiert. Schreibvorgänge erfassen nur das Delta. Das Ergebnis:

Ein 100-GB-Projekt mit zehn kleinen Branches wird als insgesamt ~100 GB abgerechnet.
Das Erzeugen eines Branches dauert unter einer Sekunde.
Branches sind verfügbar. Führen Sie eine destruktive Migration aus, werfen Sie den Branch weg, der Parent bleibt unberührt.

Benennung

Branch-Namen sind benutzersichtbare Labels, beschränkt auf das Parent-Projekt. Die Beschränkungen entsprechen denen von Projektnamen:

1–63 Zeichen.
^[a-zA-Z][a-zA-Z0-9_-]*$.
Eindeutig innerhalb des Projekts.

Die interne Branch-ID (br_<24 hex>) ist die stabile Referenz. Verwenden Sie die ID, nicht den Namen, wenn Sie gegen die API skripten; Namen können umbenannt werden.

Zustandsautomat

Ein Branch durchläuft folgende Übergänge:

creating → ready → deleting → deleted

creating — die Control Plane registriert den Branch bei der Speicherschicht. Typischerweise unter einer Sekunde; länger, wenn der Speicher unter Last steht.
ready — der Branch kann an Endpoints angehängt werden und Schreibvorgänge akzeptieren.
deleting — Kaskade im Gange: Jeder Endpoint auf diesem Branch wird gestoppt und entfernt.
deleted — terminal. Die Zeile wird zur Nachvollziehbarkeit für eine kurze Zeit aufbewahrt, dann per Garbage Collection entfernt.

Die CLI zeigt den aktuellen Zustand für jeden Branch:

keon branches list --project <project-id>

Erstellen

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

Um bei einer historischen LSN zu forken, geben Sie --parent-lsn <lsn> an:

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

Die LSN muss innerhalb des WAL-Aufbewahrungsfensters des Projekts liegen. Wenn sie darüber hinaus kompaktiert wurde, schlägt die Branch-Erstellung fehl.

Löschen

Das Löschen eines Branches kaskadiert zu jedem daran angehängten Endpoint:

Alle Endpoints auf dem Branch werden gestoppt und entfernt.
Der Branch selbst wird abgebaut.
Der Speicher wird asynchron durch Pageserver-Kompaktierung zurückgewonnen.

keon branches delete <branch-id>

Sie können den main-Branch eines Projekts nicht löschen — löschen Sie stattdessen das Projekt. Sie können jeden anderen Branch löschen, selbst wenn er Kinder hat; in diesem Fall werden die Kinder bei der Lösch-LSN dem Parent des gelöschten Branches neu zugeordnet.

Reset und Restore

Auf der Branch-Detailseite in der Konsole stellt das ⋯-Aktionsmenü zwei Re-Fork-Operationen auf jedem Nicht-Root-Branch bereit:

Reset to parent — re-forkt den Branch beim aktuellen HEAD seines Parents. Jeder Schreibvorgang auf dem Branch seit dem ursprünglichen Fork wird verworfen. Endpoints auf dem Branch suspendieren während des Tauschs kurz.
Restore to point-in-time — re-forkt den Branch bei einer gewählten LSN oder einem UTC-Zeitstempel (RFC 3339). Schreibvorgänge nach diesem Punkt werden verworfen.

Beide laufen asynchron: Die Konsole sendet die Anfrage, und der Branch kehrt zu ready zurück, sobald der Re-Fork landet. Der Root-Branch (main) kann nicht zurückgesetzt werden — es gibt keinen Parent, auf den zurückgesetzt werden könnte.

Snapshots

Ein Snapshot pinnt eine Point-in-Time-LSN, damit sie über den WAL-Aufbewahrungshorizont hinaus wiederherstellbar bleibt. Ohne einen Snapshot ist ein Wiederherstellungsziel nur erreichbar, solange sein WAL noch aufbewahrt wird; ein Snapshot hält diesen Punkt unbefristet adressierbar.

Der Snapshots-Tab auf der Branch-Detailseite listet die Snapshots des Branches auf und lässt Sie einen neuen erfassen. Jede Zeile bietet:

Restore — re-forkt den Branch bei der gepinnten LSN des Snapshots.
Delete — verwirft den Snapshot (die zugrunde liegende LSN ist nicht mehr gepinnt und kann durch Kompaktierung zurückgewonnen werden).