Use TiDB Cloud Filesystem Journals

Journals provide append-only, hash-chained event logs for agent workflows and automation pipelines running on a TiDB Cloud Filesystem. Use ti fs-journal commands to create a journal, append ordered events, search or read them, and verify the hash chain.

Prerequisites

• Install and configure TiDB Cloud CLI.
• Select a Filesystem by passing --file-system-id, setting TI_FS_FILE_SYSTEM_ID, or supplying an FS token that identifies the Filesystem.
• Provide an FS token with journal permissions through --fs-token, TI_FS_TOKEN, or the local credential stored for the selected Filesystem.

Create a journal

ti fs-journal create-journal \
  --journal-kind agent \
  --title "review task" \
  --actor agent:reviewer

Save the returned journal ID.

Append entries

ti fs-journal append-journal-entries \
  --journal-id "<journal-id>" \
  --entry-json '{"type":"review_started"}'

For supported input forms and entry fields, see the append-journal-entries reference.

Read and search entries

Read entries in sequence order:

ti fs-journal read-journal-entries --journal-id "<journal-id>"

Search across journals and entries:

ti fs-journal search-journal-entries \
  --entry-type review_started \
  --include-entries

Verify a journal

Verify that the journal's hash chain is intact:

ti fs-journal verify-journal --journal-id "<journal-id>"

What's next

• Record an Agent Workflow in a TiDB Cloud Filesystem Journal
• TiDB Cloud Filesystem Journal CLI Command Reference