📣新登場！TiDB Cloud BYOC、TiDB Cloud Filesystem、PostgreSQL-compatible TiDB Cloud Starter がパブリックプレビュー中。このページは自動翻訳されたものです。原文はこちらからご覧ください。
AI
開発者
ベストプラクティス
API

ファイルシステムのレイヤーとチェックポイントを管理する

TiDB Cloud Filesystem では、レイヤーは、コミットするまでファイルの変更をベースファイルシステムから分離します。チェックポイントを使用すると中間状態を保持でき、フォークを使用すると変更を独立して検証できます。基礎となる概念については、レイヤーとチェックポイント を参照してください。

前提条件

開始する前に、以下を確認してください。

  • TiDB Cloud CLI をインストールする。
  • 既存のディレクトリに対して read,list,write,delete 権限を持つオーナートークンまたはスコープ付きトークンを用意します。この例では、その配下に子ディレクトリを作成して削除します。
  • ファイルシステムを選択し、そのトークンを ti から利用できるようにします。利用可能なアクセス方法については、既存のファイルシステムにアクセスする を参照してください。
  • Bash または Zsh を使用し、例の実行中は同じシェルを開いたままにします。

レイヤーを作成する

トークンのスコープ内にある既存のディレクトリを選択します。オーナートークンを使用する場合は / を使い、スコープ付きトークンを使用する場合は /workspace のように、そのトークンで許可されたディレクトリに置き換えてください。例用に一意な子ディレクトリを作成します。

parent_path="/"
base_path="${parent_path%/}/layer-example-$(date +%s)-$$"
ti fs create-directory --path "$base_path"

次に、レイヤーを作成します。

ti fs create-layer \
  --base-root-path "$base_path" \
  --layer-name agent-task \
  --durability-mode restore-safe \
  --tag task=review

--base-root-path は、レイヤーがベースファイルシステムのどの部分にオーバーレイされるかを決定します。

現在の CLI で受け付けられる --durability-mode の値は restore-safe のみです。利用可能なすべてのオプションについては、create-layer コマンドリファレンス を参照してください。

以降のコマンドで使用するため、返された layer_id を保存します。

layer_id="<returned-layer-id>"

一意でない可能性があるレイヤー名ではなく、ID を使用してください。

レイヤーの変更を操作して確認する

返されたレイヤー ID を使用して、サンプルファイルをレイヤーに書き込みます。

printf 'Layer review proposal\n' | ti fs copy-file \
  --from-stdin \
  --to-remote "$base_path/proposal.md" \
  --layer-id "$layer_id"

レイヤーとその変更を確認します。

ti fs describe-layer --layer-id "$layer_id"
ti fs diff-layer --layer-id "$layer_id"

選択したファイルシステム内のすべてのレイヤーを一覧表示します。

ti fs list-layers --output text

コミットされていない変更はレイヤー内に残ります。レイヤーを選択しないファイル操作はベースファイルシステムにアクセスするため、未コミットの変更は表示されません。

--layer-id を受け取るのは copy-file、find-files、search-file-content のみです。read-file、list-files、describe-file、delete-file、move-file、create-directory は常にベースファイルシステムに対して動作します。レイヤー内のファイル内容を読み取るには、書き込み可能なレイヤーをマウントする で説明するようにレイヤーをマウントするか、チェックポイントのファイル内容を検証する を参照してください。

書き込み可能なレイヤーをマウントする

ローカルツールを使用するには、FUSE の前提条件 を満たしたうえでレイヤーをマウントします。WebDAV はレイヤーまたはチェックポイントをサポートしていません。

layer_mount="$(mktemp -d "$HOME/ti-fs-layer.XXXXXX")"
ti fs mount-file-system \
  --mount-path "$layer_mount" \
  --remote-path "$base_path" \
  --layer-ref "$layer_id" \
  --driver fuse
cat "$layer_mount/proposal.md"

想定される出力は Layer review proposal です。分離を検証するには、レイヤーを選択せずにベースファイルシステムから読み取ります。

ti fs read-file --path "$base_path/proposal.md"

レイヤーはまだコミットされていないため、not-found エラーになるはずです。ベース側でファイルが見える場合は、先に進む前に処理を止めてレイヤー選択を確認してください。

チェックポイントを作成する

チェックポイントは、レイヤーの永続的な履歴内のある時点を保持します。

レイヤーに書き込み可能な FUSE マウントがある場合は、チェックポイントを作成する前に書き込みを停止し、開いているファイルを閉じて、マウントを drain してください。

ti fs drain-file-system \
  --mount-path "$layer_mount"

次に、チェックポイントを作成します。

ti fs create-layer-checkpoint \
  --layer-id "$layer_id" \
  --checkpoint-id seed \
  --label "before review"

チェックポイントのファイル内容を検証するには、別のローカルパスにマウントします。

checkpoint_mount="$(mktemp -d "$HOME/ti-fs-checkpoint.XXXXXX")"
ti fs mount-file-system \
  --mount-path "$checkpoint_mount" \
  --remote-path "$base_path" \
  --layer-ref "$layer_id" \
  --checkpoint-id seed \
  --driver fuse
cat "$checkpoint_mount/proposal.md"
ti fs unmount-file-system --mount-path "$checkpoint_mount"

想定される出力は Layer review proposal です。チェックポイントのマウントは読み取り専用です。読み取りがハングする場合は、マウントのトラブルシューティング に従ってください。

レイヤーをフォークする

チェックポイントから独立して作業を続けたい場合は、新しい書き込み可能レイヤーをフォークします。そうでない場合は、レイヤーの変更をコミットまたは破棄する に進んでください。

ti fs fork-layer \
  --parent-layer-ref "$layer_id" \
  --layer-name experiment \
  --checkpoint-id seed

フォークで返された layer_id は別に保存します。

forked_layer_id="<returned-forked-layer-id>"

フォークの固定された祖先チェーンを確認するには、次を実行します。

ti fs list-layer-chain --layer-ref "$forked_layer_id"

フォークが作成された後は、親レイヤーと子レイヤーで行った変更は互いに独立します。

レイヤーの変更をコミットまたは破棄する

レイヤーに書き込み可能な FUSE マウントがある場合は、結果を選択する前に、書き込みプロセスを停止し、開いているファイルを閉じて、アンマウントしてください。

ti fs unmount-file-system \
  --mount-path "$layer_mount"

正常なアンマウントでは、保留中の書き込みは自動的にフラッシュされます。

結果を 1 つ選択します。コミット は変更をベースファイルシステムに適用し、ロールバック は変更を破棄します。コミットするには、次を実行します。

ti fs commit-layer --layer-id "$layer_id"

コミットが成功したら、ベースファイルシステムを通じて内容を確認します。

ti fs read-file --path "$base_path/proposal.md"

想定される出力: Layer review proposal。

コミットは、レイヤーの実効的な変更をベースファイルシステムに適用します。レイヤーが別のレイヤーをフォークして作成された場合でも、これをコミットしても変更は親レイヤーにはマージされません。

ベースファイルシステムに競合する変更が含まれている場合、コミットは自動マージされずに失敗することがあります。どのように進めるかを判断する前に、レイヤーを保持したまま、その変更内容とベースファイルシステムを確認してください。

変更を破棄する場合は、コミットの代わりに次のコマンドを実行します。

ti fs rollback-layer --layer-id "$layer_id"

ロールバックは現在のレイヤーの変更を破棄します。レイヤーを以前のチェックポイントにリセットするものではありません。チェックポイントから続行するには、そのチェックポイントから新しいレイヤーをフォークしてください。

レイヤーを削除する

フォークを作成した場合は、親より先にそれを削除してください。

ti fs delete-layer --layer-ref "$forked_layer_id"

次に、親レイヤーを削除します。

ti fs delete-layer --layer-ref "$layer_id"

レイヤーを削除すると、そのレイヤーは放棄されますが、履歴のすべてが直ちに消去されるわけではありません。レイヤーにアクティブな子孫レイヤーがある場合、このコマンドはデフォルトで失敗します。

または、レイヤーとそのアクティブな子孫レイヤーをまとめて放棄するには、--cascade を使用します。

ti fs delete-layer \
  --layer-ref "$layer_id" \
  --cascade

--cascade は、子孫レイヤーも放棄する意図がある場合にのみ使用してください。

サンプルのマウントをアンマウントし、サンプルのレイヤーを削除した後、ベースディレクトリを削除します。

ti fs delete-file --path "${base_path:?Set the example directory first}" --recursive
ti fs describe-file --path "$base_path"

describe-file から not-found エラーが返ることを確認してください。アンマウントが成功した後、rmdir "$layer_mount" と rmdir "$checkpoint_mount" を使用して作成したローカルディレクトリを削除します。サンプルファイルを削除しても、放棄されたレイヤーの履歴が直ちに消去されるわけではありません。

次のステップ

このページは役に立ちましたか？