📣

TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →

Manage File System Layers and Checkpoints

In TiDB Cloud Filesystem, a layer isolates file changes from the base file system until you commit them. You can use checkpoints to preserve intermediate states and forks to explore changes independently. For the underlying concepts, see Layers and Checkpoints.

Prerequisites

Before you begin:

Install TiDB Cloud CLI.
Have an owner token or a scoped token with read,list,write,delete permissions on an existing directory. The example creates and deletes a child directory there.
Select the file system and make its token available to ti. For available access options, see Access an Existing File System.
Use Bash or Zsh and keep the same shell open throughout the examples.

Create a layer

Choose an existing directory within your token's scope. Use / with an owner token, or replace it with the directory allowed by your scoped token, such as /workspace. Create a unique child directory for the example:

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

Then create a layer:

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

--base-root-path determines which part of the base file system the layer overlays.

restore-safe is the only --durability-mode value accepted by the current CLI. For all available options, see the create-layer command reference.

Save the returned layer_id for the remaining commands:

layer_id="<returned-layer-id>"

Use the ID rather than the layer name, which might not be unique.

Work with and inspect layer changes

Write a sample file to the layer using the returned layer ID:

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

Inspect the layer and its changes:

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

List all layers in the selected file system:

ti fs list-layers --output text

Changes that have not been committed remain in the layer. File operations that do not select the layer access the base file system and do not show its uncommitted changes.

Only copy-file, find-files, and search-file-content take --layer-id. read-file, list-files, describe-file, delete-file, move-file, and create-directory always act on the base file system. To read the contents of a file in a layer, mount the layer as described in Mount a writable layer or verify a checkpoint's file contents.

Note

copy-file with --layer-id does not support recursive copy. To copy a directory tree into a layer, mount the layer as a writable FUSE mount and copy files through the mount path.

Do not mount the same writable layer at multiple local paths concurrently. Reuse its existing mount, or unmount it before mounting the layer elsewhere.

The mount command identifies the layer with --layer-ref, while the file commands above take --layer-id. Both accept the same layer identifier value.

Mount a writable layer

To use local tools, complete the FUSE prerequisites and mount the layer. WebDAV does not support layers or checkpoints.

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"

Expected output: Layer review proposal. To verify isolation, read from the base file system without selecting a layer:

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

Expect a not-found error because the layer has not been committed. If the file is visible in the base, stop and inspect the layer selection before proceeding.

Create a checkpoint

A checkpoint preserves a point in the layer's durable history.

If the layer has a writable FUSE mount, stop writes, close open files, and drain the mount before creating the checkpoint:

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

Then create the checkpoint:

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

To verify the checkpoint's file contents, mount it at a separate local path:

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"

Expected output: Layer review proposal. Checkpoint mounts are read-only. If a read hangs, follow mount troubleshooting.

Warning

In ti v0.2.6, and in v0.2.7 installations using bundled runtime 60b63d6, checkpoint unmount can return unmounted even when the background process exited abnormally. Check the mount log before continuing; if shutdown was abnormal, keep the cache and re-verify the checkpoint's contents. For log locations and recovery steps, see Unmount returns success but the mount process exits abnormally.

Fork a layer

If you want to continue working independently from the checkpoint, fork a new writable layer. Otherwise, skip to Commit or discard layer changes.

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

Save the fork's returned layer_id separately:

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

To inspect the fork's pinned ancestry:

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

After a fork is created, changes made to the parent and child layers are independent.

Commit or discard layer changes

If the layer has a writable FUSE mount, stop writers, close open files, and unmount it before choosing an outcome:

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

A graceful unmount drains pending writes automatically.

Warning

In ti v0.2.6, and in v0.2.7 installations using bundled runtime 60b63d6, layer unmount can return unmounted even when the background process exited abnormally. Check the mount log before committing or discarding the layer; if shutdown was abnormal, keep the cache and verify required files first. For log locations and recovery steps, see Unmount returns success but the mount process exits abnormally.

Choose one outcome: commit applies the changes to the base file system; rollback discards them. To commit:

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

After a successful commit, verify the content through the base file system:

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

Expected output: Layer review proposal.

A commit applies the layer's effective changes to the base file system. If the layer was created by forking another layer, committing it does not merge the changes back into its parent layer.

If the base file system contains conflicting changes, the commit can fail instead of automatically merging them. Keep the layer and inspect its changes and the base file system before deciding how to proceed.

If you chose to discard the changes, run this command instead of committing:

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

Rollback discards the current layer changes. It does not reset the layer to an earlier checkpoint. To continue from a checkpoint, fork a new layer from that checkpoint.

Delete a layer

If you created a fork, delete it before its parent:

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

Then delete the parent layer:

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

Deleting a layer abandons it without immediately erasing all of its history. If the layer has live descendants, the command fails by default.

Alternatively, to abandon a layer and all of its live descendants together, use --cascade:

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

Use --cascade only when you intend to abandon the descendant layers as well.

After unmounting the example mounts and deleting the example layers, remove the base directory:

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

Expect a not-found error from describe-file. After successful unmount, remove the local directories you created with rmdir "$layer_mount" and rmdir "$checkpoint_mount". Deleting the example files does not erase the abandoned layers' history immediately.