ブランチ

Kisenon におけるコピーオンライトの Postgres ブランチ — LSN でのフォーク、ライフサイクル、カスケード。

ブランチ は、プロジェクトのストレージ内のログシーケンス番号（LSN）へのポインタです。作成は O(1) の行挿入であり、データをコピーしません。ブランチは書き込むにつれて分岐し、差分のみが保存されます。

モデル

すべてのプロジェクトは作成時から main ブランチを持ちます。main（または既存の任意のブランチ）から新しいブランチをフォークできます。

HEAD で — 新しいブランチは親の現在の LSN から始まります。
特定の LSN で — 新しいブランチは、親の WAL 保持ウィンドウ内の過去の LSN から始まります。これが「タイムトラベル」のケースです。WAL がまだ保持されている限り、過去のある時点からブランチを切り出せます。

ブランチでの読み取りは、ブランチが分岐するまで親のページにフォールスルーします。書き込みは差分のみを記録します。その結果は次のとおりです。

ブランチ名はユーザーに見えるラベルで、親プロジェクトにスコープされます。制約はプロジェクト名と同じです。

内部のブランチ id（br_<24 hex>）が安定した参照です。API に対してスクリプトを書くときは名前ではなく id を使ってください。名前はリネームできます。

ブランチは次の状態を遷移します。

creating → ready → deleting → deleted

creating — コントロールプレーンがブランチをストレージ層に登録しています。通常はサブ秒ですが、ストレージに負荷がかかっているとより長くかかります。
ready — ブランチをエンドポイントにアタッチでき、書き込みを受け付けます。
deleting — カスケード進行中：このブランチ上のすべてのエンドポイントが停止・削除されています。
deleted — 終端状態。行は短期間、監査のために保持され、その後ガベージコレクションされます。

CLI はすべてのブランチの現在の状態を表示します。

keon branches list --project <project-id>

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

過去の LSN でブランチを切るには、--parent-lsn <lsn> を渡します。

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

LSN はプロジェクトの WAL 保持ウィンドウ内になければなりません。すでにコンパクションで過去に追いやられている場合、ブランチの作成は失敗します。

ブランチを削除すると、それにアタッチされているすべてのエンドポイントへカスケードします。

keon branches delete <branch-id>

プロジェクトの main ブランチは削除できません。代わりにプロジェクトを削除してください。他のブランチは子を持っていても削除できます。その場合、子は削除されたブランチの親に、削除 LSN の時点で再ペアレントされます。

コンソールのブランチ詳細ページから、⋯ アクションメニューは、ルート以外の任意のブランチに対して 2 つの再フォーク操作を提供します。

親へリセット — ブランチを親の 現在の HEAD で再フォークします。元のフォーク以降にブランチで行われたすべての書き込みは破棄されます。スワップ中、ブランチ上のエンドポイントは一時的にサスペンドします。
特定時点へリストア — 選択した LSN または UTC タイムスタンプ（RFC 3339）でブランチを再フォークします。その時点以降の書き込みは破棄されます。

どちらも非同期に実行されます。コンソールがリクエストを発行し、再フォークが完了するとブランチは ready に戻ります。ルート（main）ブランチはリセットできません。リセットする先の親がないためです。

スナップショット は特定時点の LSN をピン留めし、WAL 保持の地平線を越えてもリストア可能な状態を保ちます。スナップショットがなければ、リストア対象はその WAL がまだ保持されている間しか到達できません。スナップショットはその時点を無期限にアドレス可能なまま保ちます。

ブランチ詳細ページの スナップショット タブは、ブランチのスナップショットを一覧表示し、新しいものをキャプチャできます。各行は次を提供します。