public previewのTiDB Cloud Filesystemを触ってみた
こんにちは、ゲームソリューション部のsoraです。
今回は、2026年9月15日にpublic previewが始まったTiDB Cloud Filesystemを触ってみたことについて書いていきます。
TiDB Cloudにファイルシステムを作ってMacにマウントできるところと、Claude Codeの作業メモの置き場として使えるところが気になったので、そのあたりを中心に確認していきます。
なお、本記事の内容は2026年10月13日時点のもので、public preview中のためGAで変わる可能性があります。
TiDB Cloud Filesystemとは
AIエージェントや自動化の処理向けの、サーバーレスな分散ファイルシステムです。
TiDB Cloudのリリースノートでは、以下のように紹介されています。
TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads.
サンドボックスや使い捨ての実行環境が終わっても、作業中のファイルが残ります。
別のセッションやエージェント、CIから同じファイルシステムを開いて、続きから作業できるという位置づけです。
中身はTiDBで、小さいファイルはTiDBのテーブルに、大きいファイルはオブジェクトストレージに置かれます。
ファイルとメタデータの整合性は、TiDBのトランザクションで保たれる仕組みです。
設計の背景は、以下の記事で説明されています。
操作には、同じタイミングでpublic previewになったTiDB Cloud CLI（ti）を使います。
TiDB Cloudのクラスタとの関係
TiDBの上に作られていますが、ファイルシステムを作ってもユーザーから見えるクラスタは立ちませんでした。
ファイルシステムを作ったあとにコンソールのクラスタ一覧を見ても、何も増えていません。
作成も数秒で終わっていて、裏でクラスタを起動しているような待ち時間はありませんでした。
作成時に指定できるのは表示名・ラベル・リージョンの3つだけで、プロジェクトを指定する項目もありません。
コンソールにはFilesystem用のメニューが無く、Create Resourceで作れるものの中にもありません。
作成から削除まで、すべてCLIで行う形です。
触ってみる
ti CLIのインストール
公式ドキュメントのインストールコマンドを実行します。
curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes
ti本体と、ti-drive9というもう1つのバイナリがダウンロードされます。
drive9はTiDB CloudのFilesystemインターフェースの上に作られたファイルサービスで、ファイルの操作やマウントはこのdrive9を通して行われます。
インストールが終わると、使えるリージョンが表示されます。
Config regions:
aws-us-east-1, aws-us-west-2, aws-eu-central-1, aws-ap-northeast-1, aws-ap-southeast-1
alicloud-ap-southeast-1
ti fs regions:
aws-us-east-1, aws-ap-southeast-1, aws-us-west-2, alicloud-ap-southeast-1, gcp-us-east1
ti全体のリージョンには東京（aws-ap-northeast-1）がありますが、ti fsのリージョンにはありません。
今回は、日本から近いシンガポール（aws-ap-southeast-1）を使います。
追記: 2026年10月15日にリリースされたv0.2.10で、ti fsのリージョンにazure-centralusが追加されています。
ちなみに、インストール時の表示で、匿名のテレメトリがデフォルトで有効になっていることが案内されます。
送られるのはコマンド名やフラグ名、エラーコードなどで、トークンやファイルパス、ファイルの中身は送らないと書かれていました。
止めたい場合は、~/.ti/.preferencesに以下を書きます。
[telemetry]
enabled = false
PATHを通してバージョンを確認します。
export PATH="$HOME/.ti/bin:$PATH"
echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc
ti --version
ti 0.2.9 (9fd8d7bc3dc3fa1c2b71fdef58f140511a17ed7a, 2026-10-02T17:05:01Z, darwin/arm64)
ti CLIの設定
TiDB CloudのコンソールのOrganization Settings > API KeysでAPIキーを作り、ti configureで登録します。
ti configure
Default region code (aws-us-east-1): aws-ap-southeast-1
TiDB Cloud public key: ********
TiDB Cloud private key:
{
"profile": "default",
"region_code": "aws-ap-southeast-1",
"credentials_stored": true
}
インストール直後のデフォルトのリージョンはaws-us-east-1なので、ここでaws-ap-southeast-1に変えてみました。
公式ドキュメントではpublic keyから聞かれる順で書かれていますが、実際はリージョンが最初でした。
この時点ではキーを保存しただけで、キーが正しいかは最初にTiDB Cloudへアクセスするコマンドで確かめられます。
ファイルシステムの作成
ファイルシステムを作成します。
time ti fs create-file-system \
--display-name sora-fs-trial \
--wait
--waitを付けると、ファイルシステムが使える状態になるまで待ってからコマンドが終わります。
{
"file_system_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"display_name": "sora-fs-trial",
"labels": {},
"region_code": "aws-ap-southeast-1",
"fs_token": "drive9_xxxxxxxx",
"status": "ready",
"credentials_stored": true
}
ti fs create-file-system --display-name sora-fs-trial --wait 0.04s user 0.07s system 2% cpu 4.007 total
約4秒でreadyになりました。
fs_tokenはファイルシステム全体を操作できるオーナートークンで、有効期限はありません。
CLIがローカルに自動で保存しますが、平文が表示されるのはこのときだけです。
出力にfs_tokenがそのまま出るので、画面共有中やログを貼るときは気をつける必要があります。
作成時のオプションは--helpで確認できます。
--display-name <string> Organization-visible file system display name. It is metadata, not a resource selector.
--label <string> Organization-visible metadata label in key=value form. Repeat up to 30 times; do not store secrets.
表示名とラベルの説明が「Organization-visible」となっていて、無料枠もorganization単位なので、ファイルシステムはプロジェクトではなくorganizationに属するものと考えられます。
Macへのマウント
macOSでは、macFUSEが入っていなくてもWebDAVでマウントできます。
--driverのデフォルトはautoで、FUSEが無い環境では自動でWebDAVが選ばれます。
作成時に出たfile_system_idを、環境変数に入れておきます。
ファイルシステムが1つしか無くても自動では選ばれず、設定していないと以下のエラーになります。
ti [ERROR]: file system ID is required; pass --file-system-id, set TI_FS_FILE_SYSTEM_ID, or supply an FS token
export TI_FS_FILE_SYSTEM_ID="<file_system_id>"
mkdir -p ~/tidbfs
time ti fs mount-file-system --mount-path ~/tidbfs
{
"status": "mounted",
"profile": "default",
"file_system_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"mount_path": "/Users/<user>/tidbfs",
"remote_path": "/",
"driver": "webdav",
"endpoint": {
"service": "fs",
"base_url": "https://aws-ap-southeast-1.drive9.ai",
"provider": "aws",
"api_provider": "aws",
"region_code": "ap-southeast-1",
"region_name": "aws-ap-southeast-1"
},
"write_back_cache": true
}
ti fs mount-file-system --mount-path ~/tidbfs 0.05s user 0.07s system 1% cpu 9.936 total
約10秒でマウントされ、driverはwebdavになっていました。
接続先はtidbcloud.comではなくaws-ap-southeast-1.drive9.aiです。
通信先を制限している環境で使う場合は、このドメインを許可しておく必要があります。
Finderで見ると、127.0.0.1というサーバーにWebDAVで接続した形で表示されます。
ti（drive9）がMacの中でWebDAVサーバーを動かしていて、Finderはそこに繋いでいます。
TiDB Cloud側とやり取りしているのは、そのWebDAVサーバーです。
mountコマンドで見ても、127.0.0.1のURLがマウントされていました。
http://127.0.0.1:52035/_drive9_xxxxxxxx/ on /Users/<user>/tidbfs (webdav, nodev, noexec, nosuid, mounted by <user>)
Finderでの操作
Finderで、フォルダの作成、ファイルのドラッグ＆ドロップ、フォルダへの移動、名前の変更、ゴミ箱への移動を試しました。
どの操作もできましたが、ファイルを置いたり移動したりしてから表示に反映されるまでに、毎回ラグがありました。
今回は東京のMacから、シンガポールのファイルシステムにマウントしています。
公式の製品ページのFAQでも、ノートPCへのマウントはサポートしているものの、評価にはファイルシステムと同じリージョンのクラウドVMから使うよう案内されています。
Supported, but not what we recommend for evaluation. Run it from a cloud VM in the same region as the filesystem.
マウントしたまま、別のターミナルでTiDB Cloud側の中身を見てみます。
ti fs ls --path /
{
"path": "/",
"entries": [
{
"name": ".DS_Store",
"size_bytes": 10244,
"is_dir": false
},
{
"name": "._.DS_Store",
"size_bytes": 4096,
"is_dir": false
},
{
"name": "folder",
"size_bytes": 0,
"is_dir": true
}
]
}
macOSが作る.DS_Storeと._.DS_Storeも、ファイルとして保存されていました。
ドラッグ＆ドロップしたPNGにも._のファイルが付いてくるので、1ファイル置くとリモートでは2ファイルになります。
.DS_StoreはFinderで操作するたびに書き換えられていて、8,196バイトから10,244バイトに増えていました。
後述の料金で書くとおり、小さいファイルの書き込みは単価が高いので、Macでマウントして使うときは気にしておきたいところです。
ちなみに、ドラッグ＆ドロップしてからフォルダに移動したPNGをdescribe-fileで見ると、revisionは4でした。
{
"path": "/folder/スクリーンショット 2026-10-13 11.37.29.png",
"size_bytes": 22442,
"is_dir": false,
"revision": 4,
"mtime": 1791859356,
"resource_id": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
"nlink": 1,
"content_type": "image/png"
}
確認が終わったらアンマウントします。
ti fs unmount-file-system --mount-path ~/tidbfs
アンマウントすると、ローカルの~/tidbfsは空のフォルダに戻ります。
ファイルはTiDB Cloud側に残っているので、次にマウントしたときやCLIからはそのまま見えます。
マウントなしでの操作
マウントしなくても、ti fsのコマンドでファイルを扱えます。
echo "TiDB Cloud Filesystemの検証メモ。シンガポールリージョンで作成した。" > /tmp/memo.md
time ti fs copy-file --from-local /tmp/memo.md --to-remote /memo.md
time ti fs read-file --path /memo.md
{
"operation": "copy_file",
"source_path": "/tmp/memo.md",
"target_path": "/memo.md",
"status": "copied"
}
ti fs copy-file --from-local /tmp/memo.md --to-remote /memo.md 0.04s user 0.03s system 5% cpu 1.226 total
TiDB Cloud Filesystemの検証メモ。シンガポールリージョンで作成した。
ti fs read-file --path /memo.md 0.04s user 0.04s system 6% cpu 1.113 total
アップロードも読み取りも約1秒で、Finderでの操作時のようなラグは感じませんでした。
中身での検索とファイル名での検索もできます。
ti fs grep --path / --pattern "シンガポール"
ti fs find-files --file-name-pattern "*.md"
どちらも同じ結果でした。
{
"path": "/",
"results": [
{
"path": "/memo.md",
"name": "memo.md"
}
]
}
日本語でもヒットし、書き込んだ直後の検索でもすぐに見つかりました。
デフォルトでは文字列の一致で探していて、エンベディングのプロバイダーを設定するとセマンティック検索もできるようになります。
ちなみに、v0.2.9ではlsや検索の結果で、空白を含むファイル名が最初の空白の手前で切れます。
Finderで置いたスクリーンショット 2026-10-13 11.37.29.pngは、lsではスクリーンショットと表示され、その名前で指定すると見つかりません。
ti [ERROR]: fs stat: not found
元の名前をそのまま指定すれば読めるので、データ自体は正しく保存されています。
すでにIssueが上がっていて、修正のPRは2026年10月7日にマージされています。
2026年10月13日時点の最新リリース（v0.2.9）には、まだ含まれていません。
追記: 2026年10月15日にリリースされたv0.2.10で修正されています。
Claude Codeからの利用
Claude Codeにti fsを使わせて、作業メモをTiDB Cloud Filesystemに保存させてみます。
そのあと、別のディレクトリで起動した新しいセッションから、そのメモを読んで続きをやらせます。
スコープ付きトークンの発行
Claude Codeには、/claudeの下だけを触れるトークンを渡します。
スコープ付きトークンは、パスと操作を指定して発行できます。
ti fs create-directory --path /claude
umask 077
ti fs generate-file-system-scoped-token \
--file-system-id "$TI_FS_FILE_SYSTEM_ID" \
--subject claude-code \
--ttl 24h \
--allow /claude:read,list,search,write \
--query fs_token --output text > ~/claude-fs-token
--allowで、/claudeの下の読み取り・一覧・検索・書き込みだけを許可し、削除は外しています。
ti fs list-file-system-tokens --file-system-id "$TI_FS_FILE_SYSTEM_ID" --output text
TOKEN_ID NAME SCOPE STATUS EXPIRES_AT
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx default owner active never
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx claude-code fs_scoped active 2026-10-14T02:47:26Z
作成時のオーナートークンはdefaultという名前で期限なし、今回のトークンは24時間で切れる設定になっています。
作業メモの保存
トークンとリージョンを環境変数に入れてから、Claude Codeを起動します。
mkdir -p ~/fs-trial-a && cd ~/fs-trial-a
export TI_FS_TOKEN="$(cat ~/claude-fs-token)"
export TI_REGION_CODE="aws-ap-southeast-1"
claude
スキルなどは入れず、以下のように頼みました。
ti fs コマンドでTiDB Cloud Filesystemを使えます。使い方は ti fs --help で確認してください。
TiDB Cloud Filesystemの料金体系を調べて、要点を /claude/notes/pricing.md に保存してください。
途中までで構わないので、残りの調査項目も同じファイルの末尾に書いてください。
Claude Codeはti fs --helpと、使うcopy-fileとlist-filesの--helpを読んでから、料金ページを調べてメモを書き、/claude/notes/pricing.mdに保存していました。
保存したあとに読み戻して、内容が一致することも確認しています。
途中で、Claude Codeは指示していないルート/の一覧も取ろうとしていました。
ti [ERROR]: fs ls: list :/: fs access denied
トークンの範囲外なので拒否されています。
Claude Codeはこれを、ルートの一覧は取れないが/claudeの下には書き込めたので作業には支障がない、と報告していました。
別のセッションからのメモの読み取り
Claude Codeを終了し、別のディレクトリで新しく起動します。
前の会話の内容を持っていない状態で、TiDB Cloud Filesystemに残したメモだけを手がかりに続きをやらせます。
トークンは同じものを使います。
mkdir -p ~/fs-trial-b && cd ~/fs-trial-b
export TI_FS_TOKEN="$(cat ~/claude-fs-token)"
export TI_REGION_CODE="aws-ap-southeast-1"
claude
ti fs コマンドでTiDB Cloud Filesystemを使えます。
/claude/notes/ に前回の作業メモがあります。読んで、残りの調査項目の続きをやってください。
メモを読んで残りの調査項目を把握し、そこから調査を始めていました。
公式ドキュメントに課金の詳細が少なかったため、公開されているti-cliとバックエンドのdrive9のソースまで読んで補っています。
調べ終わると、結果を前回と同じファイルに追記していました。
追記先は前回と同じ/claude/notes/pricing.mdです。
今回は同じMacの別ディレクトリで試していて、別のマシンやサンドボックスからは試していません。
なお、今回はClaude Codeを、ファイルシステムを作ったのと同じMacの同じユーザーで起動しています。
そのため、Claude Codeは~/.tiに保存されているAPIキーでti fs list-file-systemsを実行し、ファイルシステムの一覧まで取得していました。
~/.tiには作成時のオーナートークンも保存されているので、TI_FS_TOKENを設定せずにti fsを実行すれば、ファイルシステム全体を操作できてしまいます。
トークンで範囲を絞るなら、APIキーや~/.tiの設定が置かれていないサンドボックスやコンテナで動かす必要があります。
公式のガイドも、サンドボックスにはトークンとリージョンだけを渡し、ti configureの設定は置かない形になっています。
料金
読み取り・書き込みのリクエスト数、ストレージ、インターネットへの転送量による従量課金です。
単価
tiのデフォルトのリージョンのaws-us-east-1と、今回使ったaws-ap-southeast-1の単価は以下のとおりです。
| 項目 | aws-us-east-1 | aws-ap-southeast-1 |
|---|---|---|
| 読み取り（32KB未満）/ 1,000リクエスト | $0.04 | $0.04 |
| 書き込み（32KB未満）/ 1,000リクエスト | $0.50 | $0.50 |
| 読み取り（32KB以上）/ 1,000リクエスト | $0.0004 | $0.0004 |
| 書き込み（32KB以上）/ 1,000リクエスト | $0.005 | $0.005 |
| ストレージ（Performance）/ GB-月 | $0.30 | $0.36 |
| ストレージ（Pooled）/ GB-月 | $0.025 | $0.027 |
| インターネットへの転送 / GB | $0.09 | $0.12 |
リージョンはAWSのほかに、Alibaba CloudとGoogle Cloudも選べます。
Alibaba Cloudのシンガポールは、32KB以上の読み書きとストレージがAWSより安くなっていました。
全リージョンの単価は、先ほどの料金ページに載っています。
32KB未満のファイルの読み書きは、32KB以上の100倍の単価です。
ソースコードやメモのような小さいファイルを大量に書き換える使い方だと、ここが料金の中心になりそうです。
AWSの同じリージョン（us-east-1）と比べてみると、32KB以上の読み書きの単価はS3のGET / PUTと同じでした。
ストレージはPerformanceがEFS Standardと同じ$0.30 / GB-月、PooledがS3 Standardの$0.023 / GB-月に近い値です。
書き込んでみた結果
約1KBのファイルと64KBのファイルを、500個ずつ書き込んでみました。
mkdir -p /tmp/fs-cost/small
for i in $(seq -w 1 500); do head -c 1000 /dev/urandom | base64 > /tmp/fs-cost/small/file-$i.txt; done
time ti fs copy-file --from-local /tmp/fs-cost/small --to-remote /cost/small --recursive
ti fs copy-file --from-local /tmp/fs-cost/small --to-remote /cost/small 0.19s user 0.25s system 3% cpu 12.097 total
64KBの方も同じように書き込み、どちらも500ファイルが約12〜15秒で入りました。
1ファイル1リクエストとして数えると、約1KBの方は$0.25、64KBの方は$0.0025になる計算です。
書き込みから数分後にBilling > Cost Explorerを見ると、Filesystemの行は出ていませんでした。
使用量はdescribe-file-systemで確認できます。
書き込みの直後は増えておらず、少し時間を置くと反映されていました。
ti fs describe-file-system --file-system-id "$TI_FS_FILE_SYSTEM_ID" --query quota.usage
{
"file_count": 1006,
"media_file_count": 2,
"reserved_bytes": 0,
"storage_bytes": 33493552,
"video_file_count": 0
}
後片付け
ti fs delete-file-system --file-system-id "$TI_FS_FILE_SYSTEM_ID"
{
"file_system_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "deleting",
"credentials_removed": true,
"remote_deletion_state": "deleting"
}
削除は非同期で、コマンドが戻った時点ではdeletingです。
数分後にti fs list-file-systemsを見ると、一覧から消えていました。
ローカルに保存されていたトークンも、削除と同時に消されています。
最後に
今回は、public previewのTiDB Cloud Filesystemで、Macへのマウントやti fsでのファイル操作、Claude Codeの作業メモの置き場として使うところを触ってみました。
この記事がどなたかの参考になれば幸いです。
