Skill: siddontang/tidb-x (version 1.0.0)

--- name: tidb-x description: 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. --- # TiDB X **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 ``` 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 ``` ┌─────────────────────────────────────┐ │ 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](https://tidbcloud.com/free-trial/) - [Essential 101](https://www.pingcap.com/essential101/) - [TiDB Cloud AI](https://www.pingcap.com/ai) - [Architecture docs](https://docs.pingcap.com/tidbcloud/tidb-x-architecture/) - [TiDB in 2025 — X](https://medium.com/@siddontang/tidb-in-2025-x-173f3510229c) - [Context Becomes Data](https://medium.com/@siddontang/when-context-becomes-data-managing-ai-agent-context-with-tidb-307e667197bb) - [Charged-by-Query](https://medium.com/@siddontang/the-power-of-charged-by-query-how-tidb-cloud-redefines-database-economics-for-the-ai-era-f5a3e76fcf1e) - [Object Storage Playbook](https://medium.com/@siddontang/object-storage-is-rewriting-the-database-playbook-9e2dd1a81a53) - [Every Agent Needs Its Own DB](https://medium.com/@siddontang/when-every-ai-agent-needs-its-own-database-why-tidb-cloud-is-the-answer-d3ff37580284) - [TiDB for AIaaS](https://medium.com/@siddontang/why-tidb-is-the-best-database-for-ai-as-a-service-aiaas-08fe305489af) --- ## 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 ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)