TiDB X

TiDB X — object-storage-native distributed SQL for AI agent workloads. Use when building agent memory, context storage, multi-agent coordination, Web3 indexing, or any durable queryable state for AI systems.

Object-storage-native, elastic, multi-tenant SQL engine for AI agents. Charged-by-query (RU).

Quick Start (TiDB Cloud Zero)

Get a free MySQL-compatible database instantly. No sign-up, no billing.

bash

# Provision (single API call, no auth required)
curl -s -X POST "https://zero.tidbapi.com/v1alpha1/instances" \
  -H "Content-Type: application/json" \
  -d '{"tag":"my-agent"}' | tee tidb-zero.json

# Response includes: host, port, username, password, expiresAt, claimUrl
# Extract connection info
jq -r '.instance.connectionString' tidb-zero.json

# Connect (always use TLS)
export MYSQL_PWD=$(jq -r '.instance.connection.password' tidb-zero.json)
mysql -u $(jq -r '.instance.connection.username' tidb-zero.json) \
  -h $(jq -r '.instance.connection.host' tidb-zero.json) \
  -P 4000 --ssl-mode=REQUIRED

Claim your instance: The response includes claimInfo.claimUrl — open it to convert the ephemeral instance into a permanent TiDB Cloud Starter (free). Without claiming, it auto-expires in 30 days.

bash

# Get claim URL
jq -r '.instance.claimInfo.claimUrl' tidb-zero.json

Or sign up directly at https://tidbcloud.com/free-trial/

---

When To Use TiDB X

Use it when your agent needs state that is:

• Durable — survives crashes, restarts, device failure
• Shared — multiple agents read/write the same data
• Isolated — per-user or per-agent data separation
• Queryable — SQL queries, not just key-value lookup
• Auditable — who did what, when, and why
• Elastic — scales with bursty, unpredictable agent traffic
• Cost-efficient — pay per query, not per idle instance

Don't use it for: ephemeral scratchpads, pure in-memory cache, fully offline single-device apps.

---

Mental Model

text

Agent writes SQL
      │
      ▼
TiDB Server (stateless, parses + optimizes SQL)
      │
      ▼
TiKV (hot cache, ack to agent fast)
      │
      ▼
S3 Object Storage (source of truth, durable, cheap, infinite)
      │
      ▼
Background Pool (compaction, DDL — isolated, never blocks your queries)

Key ideas:

• S3 is the source of truth — not local disks
• Compute is stateless — scale up/down without data migration
• Background work is isolated — compaction never spikes your latency
• RU billing — every query has a cost in Request Units; idle = free

---

Patterns (Copy-Paste Ready)

Pattern 1: Agent Memory

Store and query agent memories. Works for support bots, coding agents, personal assistants.

sql

CREATE TABLE agent_memory (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  tenant_id VARCHAR(64),
  agent_id VARCHAR(64),
  type VARCHAR(32),
  content TEXT,
  tags JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_tenant (tenant_id)
);

-- Store a memory
INSERT INTO agent_memory (tenant_id, agent_id, type, content, tags)
VALUES ('user_123', 'support_bot', 'resolution',
  'Customer frustrated about billing. Offered 20% discount.',
  '["billing", "discount", "escalation"]');

-- Query memories
SELECT content, created_at FROM agent_memory
WHERE tenant_id = 'user_123' ORDER BY created_at DESC LIMIT 10;

-- Search by tag
SELECT * FROM agent_memory
WHERE tenant_id = 'user_123' AND JSON_CONTAINS(tags, '"billing"');

---

Pattern 2: Session Context (Append-Only)

For coding agents, research agents, or any long-running task. Append-only, never update.

sql

CREATE TABLE agent_context (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  session_id VARCHAR(128),
  step INT,
  type VARCHAR(32),       -- 'observation', 'tool_call', 'tool_output', 'decision'
  content TEXT,
  tokens INT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_session (session_id, step)
);

-- Append a step
INSERT INTO agent_context (session_id, step, type, content, tokens)
VALUES ('task_abc', 42, 'tool_output', '{"file": "auth.ts", "result": "ok"}', 800);

-- Resume after crash: reload recent steps + all decisions
SELECT * FROM agent_context
WHERE session_id = 'task_abc'
AND (step > 30 OR type = 'decision')
ORDER BY step ASC;

---

Pattern 3: Multi-Agent Task Queue

Prevent duplicate work when multiple agents run in parallel.

sql

CREATE TABLE tasks (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  task_key VARCHAR(255) UNIQUE,
  status VARCHAR(32) DEFAULT 'pending',
  agent_id VARCHAR(64),
  input JSON,
  output JSON,
  claimed_at TIMESTAMP NULL,
  completed_at TIMESTAMP NULL,
  INDEX idx_status (status)
);

-- Claim a task (atomic — only one agent wins)
UPDATE tasks SET status = 'claimed', agent_id = 'worker_3', claimed_at = NOW()
WHERE task_key = 'enrich:Union.ai' AND status = 'pending';

-- Complete
UPDATE tasks SET status = 'done',
  output = '{"investors": "NEA, Insight Partners"}',
  completed_at = NOW()
WHERE task_key = 'enrich:Union.ai' AND agent_id = 'worker_3';

---

Pattern 4: Auditable Decisions (Provenance)

When you need to explain why an agent did something.

sql

CREATE TABLE agent_decisions (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  tenant_id VARCHAR(64),
  agent_id VARCHAR(64),
  action VARCHAR(32),
  reasoning TEXT,
  source JSON,            -- {"guideline": "WHO-2026", "confidence": 0.92}
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_tenant (tenant_id)
);

-- Record a decision with reasoning
INSERT INTO agent_decisions (tenant_id, agent_id, action, reasoning, source)
VALUES ('patient_456', 'med_bot', 'recommend',
  'HbA1c = 7.8%, above 7% threshold. Recommending metformin per WHO guideline.',
  '{"guideline": "WHO-2026-diabetes", "confidence": 0.92}');

-- Audit trail
SELECT action, reasoning, source, created_at FROM agent_decisions
WHERE tenant_id = 'patient_456' ORDER BY created_at DESC;

---

Pattern 5: Blockchain Event Indexing (Web3)

Monitor and correlate on-chain activity across multiple chains.

sql

CREATE TABLE chain_events (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  chain VARCHAR(16),
  tx_hash VARCHAR(128),
  block_number BIGINT,
  from_addr VARCHAR(64),
  to_addr VARCHAR(64),
  value_wei VARCHAR(78),
  method VARCHAR(64),
  agent_id VARCHAR(64),
  tags JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_chain_block (chain, block_number),
  INDEX idx_addr (from_addr)
);

-- Index a whale swap
INSERT INTO chain_events (chain, tx_hash, block_number, from_addr, to_addr,
  value_wei, method, agent_id, tags)
VALUES ('ethereum', '0xabc...', 19500000, '0xwhale...', '0xuniswap...',
  '50000000000000000000', 'swap', 'whale_watcher', '["whale", "defi"]');

-- Find whale activity
SELECT chain, method, value_wei FROM chain_events
WHERE JSON_CONTAINS(tags, '"whale"') ORDER BY created_at DESC;

-- Cross-chain: same wallet on multiple chains
SELECT chain, COUNT(*) as txns FROM chain_events
WHERE from_addr = '0xwhale...' GROUP BY chain;

---

Pattern 6: DeFi Portfolio Agent (Web3)

Track positions, strategies, and exit decisions with full reasoning.

sql

CREATE TABLE defi_positions (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  tenant_id VARCHAR(64),
  protocol VARCHAR(64),
  chain VARCHAR(16),
  position_type VARCHAR(32),
  token_pair VARCHAR(64),
  amount DECIMAL(36,18),
  entry_price DECIMAL(36,18),
  current_value DECIMAL(36,18),
  strategy JSON,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_tenant (tenant_id)
);

-- Agent exits a position and explains why
INSERT INTO agent_decisions (tenant_id, action, reasoning, source)
VALUES ('wallet_0x123', 'exit_lp',
  'Impermanent loss hit 5.2% on ETH/USDC. Threshold is 5%. Exiting.',
  '{"tx_hash": "0xdef...", "profit_loss": -234.56}');

-- User asks: "Why did you sell?"
SELECT action, reasoning, created_at FROM agent_decisions
WHERE tenant_id = 'wallet_0x123' ORDER BY created_at DESC LIMIT 1;

---

Pattern 7: Smart Contract Event Decoder (Web3)

Index contract events with AI-generated interpretations.

sql

CREATE TABLE contract_events (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  chain VARCHAR(16),
  contract_addr VARCHAR(64),
  event_name VARCHAR(128),
  decoded_args JSON,
  block_number BIGINT,
  block_timestamp TIMESTAMP,
  agent_interpretation TEXT,
  INDEX idx_contract (contract_addr, event_name)
);

-- Index with interpretation
INSERT INTO contract_events (chain, contract_addr, event_name,
  decoded_args, block_number, block_timestamp, agent_interpretation)
VALUES ('ethereum', '0xUniV3...', 'Swap',
  '{"tokenIn": "USDC", "amountIn": 5000000, "tokenOut": "ETH", "amountOut": 2.45}',
  19500000, NOW(),
  'Large USDC→ETH swap ($5M). Possible institutional accumulation.');

-- Aggregate swaps
SELECT SUM(CAST(JSON_EXTRACT(decoded_args, '$.amountOut') AS DECIMAL(36,18))) as total_eth
FROM contract_events
WHERE contract_addr = '0xUniV3...' AND event_name = 'Swap'
AND JSON_EXTRACT(decoded_args, '$.tokenOut') = 'ETH';

---

Architecture

text

                    ┌─────────────────────────────────────┐
                    │          AI Agent Layer              │
                    │  Agent A   Agent B   Agent C  ...   │
                    └───────┬───────┬───────┬─────────────┘
                            │       │       │
                            ▼       ▼       ▼
                    ┌─────────────────────────────────────┐
                    │        TiProxy / Gateway            │
                    │   Connection routing, balancing     │
                    └───────────────┬─────────────────────┘
                                    │
           ┌────────────────────────┼────────────────────────┐
           ▼                        ▼                        ▼
  ┌────────────────┐      ┌────────────────┐      ┌────────────────┐
  │  TiDB Server   │      │  TiDB Server   │      │  TiDB Server   │
  │  (Stateless)   │      │  (Stateless)   │      │  (Stateless)   │
  └───────┬────────┘      └───────┬────────┘      └───────┬────────┘
          └───────────────────────┼───────────────────────┘
                                  │
           ┌──────────────────────┼──────────────────────┐
           ▼                      ▼                      ▼
  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
  │  TiKV (Cache)  │    │  TiKV (Cache)  │    │  TiKV (Cache)  │
  └───────┬────────┘    └───────┬────────┘    └───────┬────────┘
          └───────────────────────┼──────────────────────┘
                                  ▼
  ┌──────────────────────────────────────────────────────────┐
  │              Object Storage (S3)                          │
  │              Source of truth • Durable • Infinite          │
  └──────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────┐
  │         Background Compute (Isolated from OLTP)           │
  │   Compaction │ Import │ DDL │ Stats — never blocks you    │
  └──────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────┐
  │         TiCI — Pluggable Index Engines                    │
  │   Columnar (analytics) │ Inverted (search) │ Vector (AI)  │
  └──────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────┐
  │         RU Metering — Per-query cost attribution          │
  │   Query → 12 RU │ Query → 340 RU │ Idle → 0 RU           │
  └──────────────────────────────────────────────────────────┘

---

Editions

Edition	For	Billing
Starter	Dev/test	Free + RU
Essential	Production AI/SaaS	RU (charged-by-query)
Premium	Enterprise	Capacity-based
Dedicated	Full control	Instance-based

---

Performance

• DDL on 14.1B rows: 5.53M rows/s (5.5x improvement)
• P99/P999 latency: ~50% reduction vs previous architecture
• TiCI: 1.6K QPS at P999=203ms on complex filters

---

Key Ideas

• "Every AI agent deserves its own database — RU makes that real"
• "S3 is the new network" — storage backbone, not just backup
• "Context becomes data" — agent context needs ACID, not files
• Proven: Databricks (1M tables) → Atlassian (10M tables) → AI agents (millions of dynamic schemas)

---

Links

• Free trial
• Essential 101
• TiDB Cloud AI
• Architecture docs
• TiDB in 2025 — X
• Context Becomes Data
• Charged-by-Query
• Object Storage Playbook
• Every Agent Needs Its Own DB
• TiDB for AIaaS

---

Install This Skill

bash

mkdir -p ~/.openclaw/skills/tidb-x && curl -so ~/.openclaw/skills/tidb-x/SKILL.md https://raw.githubusercontent.com/siddontang/tidb-x-skill/main/SKILL.md