Base API

Base は、Branch のクローン元です。認証、エラー、オペレーションについては API の概要を見てください。別のノードにある Base への呼び出しは、自動でそのノードに転送されます。

Base オブジェクト

{
  "name": "prod",
  "description": "本番データのマスク済みコピー。毎週月曜に更新",
  "runtime": "postgres@18.6",
  "status": "ready",
  "status_reason": null,
  "node": "node1",
  "port": 40100,
  "created_at": "2026-11-01T09:00:00Z",
  "latest_snapshot": "s20261109",
  "snapshots": [
    { "name": "s20261109", "created_at": "2026-11-09T03:00:00Z", "public": false }
  ],
  "replicas": { "s20261109": ["node2"] },
  "replica_nodes": null,
  "holders": [
    { "node": "node1", "state": "held", "origin": true },
    { "node": "node2", "state": "held", "origin": false }
  ],
  "operation": null,
  "can": { "base.snapshot": true, "base.delete": true }
}

フィールド	意味
`status`	`provisioning`、`ready`、`maintenance`、`failed`
`node`	Base があるノード。Branch はここか、レプリカのあるノードで始まる
`snapshots[].public`	ログインなしで、誰でもその Snapshot から Branch を作れるか
`snapshots[].mask`	マスクで作った Snapshot にだけ付く。作り方の情報
`replicas`	Snapshot ごとの、コピーを持つほかのノード
`replica_nodes`	設定値。`null` はすべてのノードにコピーを置く。リストは、コピーを置くほかのノード
`holders[].state`	`held`（保持）、`pulling`（コピー中）、`draining`（コピーを手放し中）
`can`	呼び出し元がこの Base に対して実行できるアクション。コンソールがボタンの表示に使う

`GET /v1/bases`

アクション base.read。Base を名前順に一覧します。GET /v1/bases/{name}（同じアクション）は 1 つ返します。

`GET /v1/public/bases`

アクション base.public。公開 Snapshot を持つ Base を一覧します。ログインなしで使えます。

`POST /v1/bases`

アクション base.create。Base を作り、最初の Snapshot を取ります。種類 base.create のオペレーションを付けて 202 を返します。

フィールド	型	意味
`name`	string、必須	Base の名前
`runtime`	string、必須	`engine@version`。ノードにインストール済みのもの
`dump`	string	読み込む `.sql` または `.sql.gz` のダンプ。アップロード ID（`upload:...`、後述）かノード上のパス。省略すると空の Base
`description`	string	説明。1000 文字まで
`node`	string	Base を作るノード。`dump` のパスはそのノードで読む。省略時は呼び出したノード
`replica_nodes`	array または null	`null` または省略: すべてのノードにコピーを置く。`[]`: Base のあるノードだけ。リスト: それらのノードにも置く

エラー: 409 already_exists、404 runtime_not_installed。

`PATCH /v1/bases/{name}`

アクション base.describe。説明を変更します。200 で Base を返します。

{ "description": "マスク済みの本番データ" }

`DELETE /v1/bases/{name}`

アクション base.delete。204 を返します。Branch がまだ使っている Base は 409 in_use です。

`POST /v1/bases/{name}/start` と `/stop`

アクション base.start、base.stop。Base のデータベースサーバーを起動、停止します。204 を返します。

`POST /v1/bases/{name}/snapshots`

アクション base.snapshot。Base のサーバーを正常に停止して Snapshot を取り、サーバーを再び起動して、レプリカを持つノードへ Snapshot をコピーします。種類 base.snapshot のオペレーションを付けて 202 を返します。サーバーが正常に停止しなければ、unclean_shutdown で失敗し、Snapshot は取られません。

`PATCH /v1/bases/{name}/snapshots/{snapshot}`

アクション base.publish。Snapshot を公開または非公開にします。200 で Base を返します。

{ "public": true }

`DELETE /v1/bases/{name}/snapshots/{snapshot}`

アクション base.snapshot_delete。204 を返します。最新の Snapshot（409 conflict）と、Branch が使っている Snapshot（409 in_use）は削除できません。Prune old snapshots の設定が有効なら、使われていない古い Snapshot は自動でも削除されます。

`POST /v1/bases/{name}/mask`

アクション base.mask。別の Base のマスク済みコピーを、この（空の）Base に書き込み、Snapshot を取ります。マスクはマスキングツール（Greenmask などのモジュール）が行うため、インストールしておく必要があります。種類 base.mask のオペレーションを付けて 202 を返します。

フィールド	型	意味
`source`	string、必須	コピー元の Base
`snapshot`	string	コピー元の Snapshot。省略時は最新
`masker`	string、必須	マスキングツールのモジュール名（例: `greenmask`）
`rules`	string	マスキングツールが受け付ける形式のルール

`POST /v1/bases/{name}/sql`

アクション base.sql。Base のサーバー（停止中なら起動）で、管理者として SQL を実行します。次の Snapshot の前にデータを変更するために使います。204 を返します。文が失敗すると 422 query_failed です。

{ "sql": "INSERT INTO shop.products (name) VALUES ('new item');" }

`POST /v1/bases/{name}/load`

アクション base.load。Base の現在のデータの上に、ダンプを読み込みます。種類 base.load のオペレーションを付けて 202 を返します。

フィールド	型	意味
`dump`	string、必須	アップロード ID か、Base のあるノード上のパス
`snapshot`	boolean	読み込んだ後に Snapshot を取る

既存の Branch には影響しません。

アップロード

ダンプは、ノードにコピーする代わりに、API で送れます。

`POST /v1/uploads`

アクション base.upload。リクエストボディはファイルそのものです（JSON ではありません）。Content-Length ヘッダーと、クエリパラメーター name（ファイル名）が必要で、node も指定できます。ファイルはそのノードに保存され、POST /v1/bases や /load で使うまで、返された ID で参照できます。

curl -sk -H "$AUTH" -H 'Content-Type: application/gzip' \
  --data-binary @prod.sql.gz "$DBB/uploads?name=prod.sql.gz"
# {"id":"upload:01J...","name":"prod.sql.gz","size":104857600,"node":"node1"}

エラー: 411 length_required、413 too_large（Largest dump upload の設定を超えた）、507 no_space（ノードの ZFS プールに空きが足りない）。

`GET /v1/uploads/room`

アクション base.upload。このノードが今受け付けられるアップロードの大きさを返します。{"node": "node1", "max_bytes": 21474836480, "reason": "limit"} の形で、reason は limit（設定による上限）か pool（空き容量）です。

定期更新（refresh）

Base は、元のデータベースから定期的に更新できます。元をダンプし、読み込み、Snapshot を取ります。every は 1h 以上にします。

`GET /v1/bases/{name}/refresh`

アクション base.refresh.read。スケジュールを返します。設定がなければ 404 not_found です。元のパスワードは返しません。

{
  "base": "prod",
  "engine": "postgres",
  "source": { "host": "db.internal", "port": 5432, "user": "reader", "password_set": true, "databases": ["app"] },
  "every": "24h0m0s",
  "updated_at": "2026-11-09T12:00:00Z",
  "last_run": { "started_at": "2026-11-10T03:00:00Z", "finished_at": "2026-11-10T03:12:00Z", "ok": true, "error": null },
  "next_run": "2026-11-11T03:00:00Z",
  "operation": null
}

`PUT /v1/bases/{name}/refresh`

アクション base.refresh。スケジュールを設定または変更します。上のスケジュールを 200 で返します。password を省略すると、保存済みのパスワードが残ります。

{
  "source": { "host": "db.internal", "port": 5432, "user": "reader", "password": "...", "databases": ["app", "billing"] },
  "every": "24h"
}

`DELETE /v1/bases/{name}/refresh`

アクション base.refresh。スケジュールを止めます。204 を返します。

`POST /v1/bases/{name}/refresh/run`

アクション base.refresh。今すぐ更新します。種類 base.refresh のオペレーションを付けて 202 を返します。

レプリカ

`PUT /v1/bases/{name}/replicas`

アクション base.replicas。Base のコピーを持つノードを選びます。ボディには replica_nodes が必要です。null はすべてのノード、[] は Base 自身のノードだけ、リストは指定したノード名です。200 で Base を返します。外したノードは、そのノードの Branch がその Base を使わなくなった時点でコピーを手放します。

{ "replica_nodes": ["node2"] }

Base API

Base オブジェクト

GET /v1/bases

GET /v1/public/bases

POST /v1/bases

PATCH /v1/bases/{name}

DELETE /v1/bases/{name}

POST /v1/bases/{name}/start と /stop

POST /v1/bases/{name}/snapshots

PATCH /v1/bases/{name}/snapshots/{snapshot}

DELETE /v1/bases/{name}/snapshots/{snapshot}

POST /v1/bases/{name}/mask

POST /v1/bases/{name}/sql

POST /v1/bases/{name}/load