📣

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

Mount a File System on macOS

On macOS, you can mount a file system in TiDB Cloud Filesystem as a local directory and access its files with your usual applications and tools.

For general file access, WebDAV requires no additional mount software. Use FUSE with macFUSE to mount layers or checkpoints, or to flush pending writes while keeping the mount running.

For automatic driver selection, TiDB Cloud CLI (ti) prefers FUSE when macFUSE is installed and uses WebDAV otherwise. The examples specify a driver explicitly to make the choice clear.

Note

TiDB Cloud Filesystem is currently in public preview. Its features and interfaces are subject to change without notice.

Prerequisites

Before you begin:

Install TiDB Cloud CLI (ti).
Make the file system and its token available to ti. See Access an Existing File System.

Use Bash or Zsh and keep the same shell open for each procedure.

Mount with WebDAV

Use an owner token or a scoped token with read,list,write,delete permissions on the remote directory. These permissions cover both verification and cleanup. Upload a small file, update it through WebDAV, and verify the update after unmounting.

For read-only access through WebDAV, use a scoped token with only read and list permissions and mount without --read-only; WebDAV rejects that option. The token enforces read-only access at the service. Follow the read-only sharing example to mount, read an existing file, and unmount. The procedure below requires write permissions to upload, update, and clean up a sample file.

For a local read-only mount, use macFUSE with --driver fuse --read-only.

Select the remote directory and create an empty local mount directory. For a token scoped to one directory, replace / with that directory's path:
```
remote_path="/"
mount_dir="$(mktemp -d "$HOME/ti-fs-webdav.XXXXXX")"
```

Upload a unique sample file to that remote directory so you can verify that the mount can read an existing remote file:

test_file="mount-check-$(date +%s)-$$.txt"
printf 'Hello from the service\n' | ti fs copy-file \
  --from-stdin --to-remote "${remote_path%/}/$test_file"

Mount the directory with WebDAV:
```
ti fs mount-file-system \
  --remote-path "$remote_path" \
  --mount-path "$mount_dir" \
  --driver webdav
```
The remote directory becomes the mount root. The mount runs in the background until you unmount it.
Read the uploaded file:
```
cat "$mount_dir/$test_file"
```
Expected output: Hello from the service. If a file operation takes longer than 30 seconds, interrupt it with Ctrl+C and follow mount troubleshooting before continuing.

Update the file through the mount:

printf 'Hello from macOS\n' > "$mount_dir/$test_file"

Close applications using the mount and unmount it normally:
```
ti fs unmount-file-system --mount-path "$mount_dir"
```
WebDAV does not support drain-file-system. If unmount fails, keep the machine and local mount data available and follow Finish safely.
After successful unmount, read the update directly from the service:
```
ti fs read-file --path "${remote_path%/}/$test_file"
```
Expected output: Hello from macOS.

Delete the sample file and empty mount directory:

ti fs delete-file --path "${remote_path%/}/$test_file"
rmdir "$mount_dir"

The file system remains available for reuse.

Note

Browsing a mount in Finder, with either driver, writes .DS_Store files and ._ companion files into the file system. They stay there after you unmount, they consume storage and appear in the file system's file count, and anyone holding a token for that path can see them. Delete both kinds if you do not want to share them:

ti fs delete-file --path "${remote_path%/}/.DS_Store"
ti fs delete-file --path "${remote_path%/}/._.DS_Store"

Use macFUSE when you need FUSE features

Use FUSE instead of WebDAV when you need to:

Mount a layer or checkpoint.
Flush pending writes with drain-file-system while keeping the mount running.

To use FUSE on macOS:

Install macFUSE and complete any installation or security approval steps required by your macOS version.
Installing ti does not install macFUSE.
Prepare the local mount directory:
- If a mount is already active at $HOME/workspace, unmount it before reusing the same directory:
```
ti fs unmount-file-system --mount-path "$HOME/workspace"
```
- Ensure that $HOME/workspace exists:
```
mkdir -p "$HOME/workspace"
```
Mount the file system with FUSE:
```
ti fs mount-file-system \
  --mount-path "$HOME/workspace" \
  --driver fuse
```
The mount continues running in the background after the command returns, so closing the terminal does not unmount it.
Run the FUSE mount and the applications that access it as the same OS user.
If your file system token grants access only to a specific remote path, add --remote-path as described in Mount only part of the file system instead of mounting the file system root.
Layer and checkpoint mounts require FUSE, and checkpoint mounts are always read-only. For details, see Manage File System Layers and Checkpoints.
If you need pending writes to reach the file system while keeping the mount running, see FUSE write behavior. For command syntax, see drain-file-system.
When you are finished, stop applications from writing to the mount, close open files, and unmount it:
```
ti fs unmount-file-system --mount-path "$HOME/workspace"
```
A successful FUSE unmount flushes pending writes. You do not need to run drain-file-system before a normal unmount.

Unmounting removes the local mount but does not delete the file system or its data.

Flush FUSE writes without unmounting

If you need pending writes to reach the file system while keeping the FUSE mount running, stop applications from writing to the relevant files and close those files first. Then drain the mount:

ti fs drain-file-system \
  --mount-path "$HOME/workspace" \
  --timeout 30s

A successful drain confirms that pending writes have reached the file system while leaving the mount running. If the drain times out or returns an error, keep the mount and machine available, resolve the error, and verify the files before ending the session or telling another user that the updates are ready. WebDAV does not support drain-file-system. For command syntax, see drain-file-system.

Troubleshoot mount issues

If a WebDAV mount fails to start:

Make sure the local mount directory exists and is writable.
Make sure another mount is not already using the same local directory.
Check the diagnostic log path reported by ti for the underlying error.

If a FUSE mount fails to start:

Make sure macFUSE is installed.
Complete any macOS security approvals required by macFUSE.
Make sure the mount and the application that accesses it run as the same OS user.
Make sure another mount is not already using the same local directory.
Check the diagnostic log path reported by ti.

If unmounting fails, keep the mount process and machine running until you resolve the error and verify that required files have reached the file system. Do not remove local mount data while pending writes might remain.

For additional mount errors, see Troubleshoot TiDB Cloud Filesystem.

What's next

Mount a File System for read-only mounts, mounting layers or checkpoints, and other common mount options.
Manage File System Layers and Checkpoints to work with layers and checkpoints through FUSE.
Share a File System Across Machines to give another user or environment access to the file system.