openclaw/docs/tools/tidb.md

summary	read_when
TiDB tool (mysql CLI) for durable structured storage and analysis	You want to store/query large structured data in TiDB You use TiDB Cloud and have a Connect panel .env snippet

TiDB tool

Clawdbot ships a tidb tool that talks to TiDB over the MySQL protocol by invoking the local mysql CLI.

Use it when you want results to be durable and queryable (analysis, reporting, large tables), not for small ephemeral notes.

Quick setup with TiDB Cloud (recommended)

In TiDB Cloud, open your cluster Connect panel:

1. Set Connect With → .env
2. Copy the block like:

DB_HOST=gateway01.us-west-2.prod.aws.tidbcloud.com
DB_PORT=4000
DB_USERNAME='your.cluster.id.root'
DB_PASSWORD='<PASSWORD>'
DB_DATABASE='test'

3. Paste it into the gateway host env file:

cat >> ~/.clawdbot/.env <<'EOF'
DB_HOST=gateway01.us-west-2.prod.aws.tidbcloud.com
DB_PORT=4000
DB_USERNAME='your.cluster.id.root'
DB_PASSWORD='<PASSWORD>'
DB_DATABASE='test'
EOF

4. Enable the tool in ~/.clawdbot/clawdbot.json:

{
  tools: {
    tidb: { enabled: true }
  }
}

That is it. Clawdbot will read DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD/DB_DATABASE automatically.

Notes:

• For *.tidbcloud.com hosts, Clawdbot defaults to mysql --ssl-mode=VERIFY_IDENTITY.
• Credentials in env vars are visible to the gateway process; use a dedicated database user with minimal privileges.

Alternative: Connection string (copy, do not build by hand)

If TiDB Cloud shows a General connection string like:

mysql://your.cluster.id.root:<PASSWORD>@gateway01.us-west-2.prod.aws.tidbcloud.com:4000/test

Put it directly into ~/.clawdbot/.env as TIDB_URL:

cat >> ~/.clawdbot/.env <<'EOF'
TIDB_URL=mysql://your.cluster.id.root:<PASSWORD>@gateway01.us-west-2.prod.aws.tidbcloud.com:4000/test
EOF

Using the tool

Call the tidb tool with:

• sql (required)
• database (optional override)
• format: rows (default, parses first result set) or raw
• timeoutSeconds (optional)

Example:

SELECT VERSION();

See also: Env vars.