busabase-cli backup と restore で Busabase の space を 1 つの持ち運び可能なアーカイブにバックアップし、完全な履歴・元の id・実ファイルごと復元する。

バックアップと復元

busabase-cli backup は、Busabase の space 全体 — すべてのノード、base、レコード、フィールド値、ドキュメント本文、アップロード済みファイル、そして(任意で)Change Request / commit の完全な履歴 — を 1 つの持ち運び可能な .bbdump アーカイブにエクスポートし、busabase-cli restore がそれを元に戻します。ディザスタリカバリ、ローカルの自己ホスト環境と Cloud の間での space の移行、リスクのある変更を行う前のオフラインスナップショットの保存などに使います。

このページではかつて、独立した busabase-dump CLI を busabase-dump export / busabase-dump import というコマンド名で説明していました。このツールがリリースされることはなく、同じワークフローは busabase-cli に組み込まれています — ツールも、ログインも、設定ファイルも 1 つで済みます。npm i -g busabase-cli でインストールしてください。

インストールと実行

npx busabase-cli backup
npx busabase-cli restore space.bbdump

~/.busabase/.env にすでにベース URL・API キー・space id が保存されていれば、別途設定は不要です — busabase-cli login が書き込むのと同じファイルを読み込みます。エージェントをすでに接続済みなら(参照:エージェントを持ち込む)、バックアップは追加設定なしでそのまま使えます。

space をバックアップする

npx busabase-cli backup -o space.bbdump

space 内のすべてのテーブル — ノード、base/フィールド/ビュー、レコードとフィールド値、レコードリンク、asset とそのアップロード済みバイト列、ドキュメント本文、そして(デフォルトで)commit/Change Request/レビュー/監査イベントの完全な履歴 — を走査し、1 つの .bbdump ファイル(ストリーミング tar アーカイブ、zstd 圧縮)に書き出します。

フラグ	効果
`-o, --out-file <file>`	出力アーカイブのパス(デフォルト `space.bbdump`)
`--no-history`	commits/Change Requests/operations/comments/reviews/監査イベントを除外し、現在の状態のみを保持
`--space-id <id>`	バックアップする space(デフォルト:`BUSABASE_SPACE_ID` / `~/.busabase/.env`)

Vault のシークレットと webhook の署名キーはバックアップに含まれません — .bbdump アーカイブは、資格情報を漏らすことなく安全に保存・転送できます。

space に復元する

npx busabase-cli restore space.bbdump

復元は完全な忠実度(full-fidelity)で行われます。すべてのノード、base、レコード、履歴エントリが元の idのまま戻るため、レコード間のリンクや参照はそのまま維持されます。そのため、復元先の space は本当に空である必要があります(自動作成される workspace ルートのみ)— restore はすでにコンテンツがある space への書き込みを拒否するため、復元によって既存の作業内容が黙って上書き・マージされることはありません。

各テーブルの書き込み完了後、restore は整合性チェックを実行し、参照切れ(復元されなかったフィールドを指すフィールド値、対応するレコードが欠けているレコードリンク、ストレージへの書き込みに失敗したファイルなど)を警告として報告します。これにより、復元された space を信頼する前に何を確認すべきかが明確になります。

復元先を選ぶ

--base-url / --space-id で、コピーの復元先(同じサーバー上の別の space、別の自己ホスト環境、Cloud の workspace など)を指定します:

npx busabase-cli restore space.bbdump \
  --base-url https://busabase.com \
  --api-key <token> \
  --space-id <target-space-id>

backup と export — どちらを使うべきか?

目的が異なる 2 つの機能であり、フォーマットも意図的に分けられています:

	`backup` / `restore`	`export` / `install`
フォーマット	圧縮された 1 つの `.bbdump` アーカイブ	GitHub にプッシュできる、読めて diff も取れるディレクトリツリー
含まれるもの	すべて:生の行データ、元の id、履歴、コメント、レビュー、監査イベント、権限	現在の状態のみ — コンテンツそのもので、その過去は含まない
対象の space	空である必要がある	既存の space に、そこにあるものと並べてインストールする
id	そのまま保持される	インストール時に新しく採番される
用途	ディザスタリカバリ、space 全体の移行	テンプレートの共有、git でのコンテンツのバージョン管理

「この base のコピーを渡して、そこから始めてもらいたい」なら export です。「サーバーが飛んでも、この space をそっくりそのまま再構築できるようにしたい」なら backup です。

設定

他のすべての Busabase クライアントと同じ優先順位です:

項目	フラグ	環境変数	保存先
ホスト	`--base-url <url>`	`BUSABASE_BASE_URL`	`~/.busabase/.env`
API キー	`--api-key <token>`	`BUSABASE_API_KEY`	`~/.busabase/.env`
Space	`--space-id <id>`	`BUSABASE_SPACE_ID`	`~/.busabase/.env`

backup/restore がホストに接続できない、または 401/403 が返る場合はトラブルシューティングを参照してください — busabase-cli の他の部分と同じホスト/認証のルールがここにも適用されます。

サポートしていない機能

--state-only は認識されますが、実装されることはありません — export / install に取って代わられたためです。「履歴なしのコンテンツ」という同じ需要を、実際に読めて diff も取れるフォーマットで満たします。backup --state-only を実行すると、その案内を表示して終了します。

以下は CLI が認識はしますが、まだ実装されていません — 予期しない動作をする代わりに、明確なエラーで即座に失敗します:

--resume(途中で中断した復元の再開)
--into-folder(state-only アーカイブにのみ関係します — 代わりに install --into-folder を使ってください)

関連ページ:インストールとエクスポート · エージェントを持ち込む · API トークン · REST API · トラブルシューティング

バックアップと復元

On this page