ランタイム、クラスター、オペレーション API

認証、エラー、オペレーションの仕組みは API の概要を見てください。

ランタイム

ランタイムは、データベースエンジンのバージョンで、engine@version と書きます（mysql@8.4.13、postgres@18.6）。

`GET /v1/runtimes`

アクション runtime.read。このノードにインストールされているランタイムを一覧します。?node=<name> で別のノードを指定できます。

{ "items": [ { "runtime": "postgres@18.6", "engine": "postgres", "version": "18.6" } ], "next_cursor": null }

`GET /v1/runtimes/available`

アクション runtime.read。パッケージカタログが、このノード向けに提供する MySQL と PostgreSQL のバージョンを一覧します。項目の形は同じです。

`POST /v1/runtimes`

アクション runtime.install。ランタイムをインストールします。クラスターでは、全ノードに記録されてインストールされ、新しく参加するノードも同じものをインストールします。種類 runtime.install のオペレーションを付けて 202 を返します。

{ "runtime": "postgres@18.6" }

エラー: 422 runtime_unavailable（カタログにない）、409 already_exists。

`DELETE /v1/runtimes/{engine}/{version}`

アクション runtime.remove。ランタイムを削除します（例: DELETE /v1/runtimes/postgres/18.6）。クラスターでは全ノードから削除します。?node=<name> を付けると、そのノードだけが対象です。204 を返します。Base や Branch が使っている場合、またはダウンしているノードがある場合は 409 in_use で、該当するノードを示します。

クラスターとノード

`GET /v1/cluster`

アクション cluster.read。このノードから見たクラスターを返します。1 ノードだけの場合は "mode": "single" です。

{
  "mode": "cluster",
  "leader": "node1",
  "protocol": 3,
  "nodes": [
    {
      "name": "node1", "host": "node1", "address": "10.0.0.1:7070", "version": "1.4.0",
      "leader": true, "voter": true, "down": false, "last_seen": "2026-11-09T12:00:00Z",
      "pool_size": 1000000000000, "pool_free": 640000000000,
      "runtimes": ["postgres@18.6"], "modules": ["auth 1.4.0"],
      "metrics": { "time": "2026-11-09T12:00:00Z", "cpu": 12.5, "load1": 0.4, "mem_total": 17179869184, "mem_used": 6442450944, "net_rx": 1200, "net_tx": 800, "arc": 2147483648 },
      "arc_max_mb": 4096
    }
  ]
}

ダウンしているノードは down: true です。voter は、そのノードがクラスターの変更に投票するかどうかを示します。ZFS キャッシュの上限を適用できなかったときは、arc_problem が付きます。

`GET /v1/nodes/{name}/metrics`

アクション cluster.read。ノードの直近の性能サンプル（CPU、ロード、メモリ、ネットワーク、ZFS キャッシュ）を古い順に、{"items": [...]} で返します。コンソールの直近 1 時間のグラフに使われています。

`GET /v1/metrics`

アクション metrics.read。このノードの Prometheus テキスト形式（text/plain; version=0.0.4）のメトリクスです。クラスターとノードの状態、Branch、Base、レプリケーション、モジュールの問題、API リクエスト数が含まれます。

`POST /v1/cluster/token`

アクション cluster.token。ノードをクラスターに参加させるためのトークンを作ります。ノードのローカルソケット（db-branch cluster token）でだけ使えます。HTTPS では 403 socket_only、クラスターを組んでいないノードでは 409 not_clustered です。

`GET /v1/capabilities`

アクション capability.read。このノードのバージョンと、動いているモジュール、モジュールが追加するコンソールのページを返します。

{ "version": "1.4.0", "node": "node1", "modules": ["auth 1.4.0"], "pages": [] }

オペレーション

`GET /v1/operations`

アクション operation.read。オペレーションを新しい順に一覧します。完了したものは、新しい 200 件まで残ります。

`GET /v1/operations/{id}`

アクション operation.read。オペレーションを 1 つ返します。ログインなしでは、匿名の Branch 作成で始まったオペレーションに対して使えます。未知の ID は 404 not_found です。フィールドは概要にあります。

オペレーションの種類は、branch.create、branch.reset、branch.recreate、branch.delete、base.create、base.snapshot、base.mask、base.load、base.refresh、runtime.install です。

イベント

`GET /v1/events`

アクション event.read。概要で説明した Server-Sent Events のストリームです。