Branch API

ベース URL と認証は API の概要にあります。表の「アクション」は、その呼び出しで権限を判定するときの名前です。

Branch オブジェクト

{
  "name": "feature-x",
  "id": "alice/feature-x",
  "owner": "alice@example.com",
  "access": "private",
  "status": "ready",
  "status_reason": null,
  "base": "prod",
  "snapshot": "s20261109",
  "runtime": "postgres@18.6",
  "node": "node1",
  "created_at": "2026-11-09T12:00:00Z",
  "expires_at": "2026-11-12T12:00:00Z",
  "reset_at": null,
  "storage": { "used": 1048576, "referenced": 83886080 },
  "connection": { "host": "node1", "port": 41203, "user": "feature-x" },
  "proxy": { "host": "node1", "port": 6133, "user": "feature-x" },
  "operation": null
}

フィールド	意味
`status`	`provisioning`、`ready`、`resetting`、`deleting`、`failed`、`lost`（ノードが失われた。`recreate` を参照）
`status_reason`	`failed` や `lost` の理由。それ以外は `null`
`id`	オーナーがいれば `owner/name`（メールアドレスのオーナーは @ の前だけ）、いなければ名前
`access`	`private`（専用のパスワード。オーナーと管理者が接続できる）または `open`（クラスター共通のパスワード。誰でも接続できる）
`snapshot`	Branch の元になった Base の Snapshot
`expires_at`	自動で削除される時刻。期限なしは `null`
`storage`	Branch が書き込んだバイト数（`used`）と、参照できるバイト数（`referenced`）。不明なら `null`
`connection`	直接接続: ノードのホスト、Branch 専用のポート、ユーザー（データベース名は含まれない。`/dsn` を使う）
`proxy`	ノードのプロキシ経由でユーザー名で接続する情報。プロキシがなければ `null`
`operation`	その Branch で実行中のオペレーション（`id`、`kind`）。なければ `null`

`GET /v1/branches`

アクション branch.read。Branch を名前順に一覧します。

{ "items": [ { "name": "feature-x", "status": "ready", "...": "..." } ], "next_cursor": null }

`POST /v1/branches`

アクション branch.create。Base をクローンして新しい Branch を作ります。種類 branch.create のオペレーションを付けて 202 を返します。

フィールド	型	意味
`name`	string、必須	Branch の名前
`base`	string、必須	クローンする Base
`snapshot`	string	クローンする Snapshot。省略時は Base の最新
`ttl`	string	寿命（`72h` など）。省略時はクラスターの Default TTL の設定、なければ期限なし
`init_sql`	string	クローン後に 1 度だけ実行する SQL。リセットするとこの状態に戻る
`node`	string	Branch を置くノード。省略時は、その Snapshot を持つノードから負荷で選ぶ
`owner`	string	管理する人。省略時は呼び出した本人。ほかの人を指定できるのは管理者だけ
`access`	string	`private`（既定）または `open`

エラー: 404 not_found（Base がない）、409 already_exists、503 no_capacity。open な Branch の共通パスワードは Settings で設定します。

ログインしていない呼び出し元は、公開した Snapshot からだけ Branch を作れます。その Branch は常に open で、TTL は Anonymous branch TTL が上限になり、同時に存在できる数も限られます（Settings の Anonymous branches）。

`GET /v1/branches/{name}`

アクション branch.read。Branch を 1 つ返します。

`PATCH /v1/branches/{name}`

アクション branch.extend。期限を、現在時刻に ttl を足した時刻にします。200 で Branch を返します。

{ "ttl": "24h" }

`DELETE /v1/branches/{name}`

アクション branch.delete。種類 branch.delete のオペレーションを付けて 202 を返します。削除できるのは ready、failed、lost の Branch です。lost の Branch の削除は記録だけ残り、ノードが戻ったときに完了します。

`POST /v1/branches/{name}/reset`

アクション branch.reset。変更をすべて破棄し、作成直後（init_sql を実行した後）の状態に戻します。種類 branch.reset のオペレーションを付けて 202 を返します。Branch は ready である必要があり、そうでなければ 409 conflict です。

`POST /v1/branches/{name}/recreate`

アクション branch.recreate。lost の Branch を、その Snapshot を持つノードに作り直します。種類 branch.recreate のオペレーションを付けて 202 を返します。クエリパラメーター node でノードを指定でき、省略すると自動で選びます。作成後に Branch へ書き込んだデータは戻りません。

`GET /v1/branches/{name}/dsn`

アクション branch.connect。パスワードを含む接続 URL を返します。呼び出しごとに監査ログへ記録されます。

{ "dsn": "postgres://feature-x:s3cret@node1:41203/postgres" }

?via=proxy を付けると、ノードのプロキシのポートを指す URL になります。ノードにプロキシがない、または Branch に専用のユーザーがまだない場合は 409 not_routable です。

`POST /v1/branches/{name}/query`

アクション branch.query。ready の Branch で、Branch 自身のユーザーとして SQL を 1 文実行します。

フィールド	型	意味
`sql`	string、必須	1 つの文
`max_rows`	number	返す行数。最大 1000（既定も 1000）

{
  "columns": ["id", "email"],
  "rows": [["1", "user1@example.invalid"], ["2", null]],
  "truncated": false,
  "millis": 4
}

値は文字列で、SQL の NULL は null です。行を返さない文では、columns と rows の代わりに affected（変更した行数）を返します。文が失敗すると 422 query_failed、Branch が ready でなければ 409 conflict です。

所有者による制限

管理者（または full トークン）は、すべての Branch を扱えます。それ以外の呼び出し元は、すべての Branch を読めますが、変更、接続、クエリができるのは自分の Branch だけです。例外は open の Branch で、誰でも接続とクエリができます。有償モジュールでは、チームメイトと Branch を共有することもできます。それ以外は 403 forbidden です。