tidb-query-tuning
TiDB Query Tuning
Use this skill to diagnose and resolve TiDB query performance issues. It follows a rigorous workflow from symptom identification to verified solution.
Workflow
- Capture the current plan & clues:
- Run
EXPLAIN ANALYZE <query>to get actual execution stats. - Compare
estRowsvsactRows— large divergence means stale or missing statistics. - Note the most expensive operators (wall time, memory, rows processed).
- Use PLAN REPLAYER: Run
PLAN REPLAYER DUMP EXPLAIN [ANALYZE] <query>;to export comprehensive on-site information (version, config, stats, plan) to a ZIP file. - Use Debug API: Use TiDB HTTP API (port 10080) to pull runtime info:
/debug/pprof,/stats/dump/{db}/{table}, or/schema/{db}/{table}. - Check Bindings: Run
SHOW GLOBAL BINDINGS;to see if existing plan baselines are affecting the query.
- Run
More from pingcap/agent-rules
tidb-sql
Write, review, and adapt SQL for TiDB with correct handling of TiDB-vs-MySQL differences (VECTOR type + vector indexes/functions, full-text search, AUTO_RANDOM, optimistic/pessimistic transactions, foreign keys, views, DDL limitations, and unsupported MySQL features like procedures/triggers/events/GEOMETRY/SPATIAL). Use when generating SQL that must run on TiDB, migrating MySQL SQL to TiDB, or debugging TiDB SQL compatibility errors.
38pytidb
PyTiDB (pytidb) setup and usage for TiDB from Python. Covers connecting, table modeling (TableModel), CRUD, raw SQL, transactions, vector/full-text/hybrid search, auto-embedding, custom embedding functions, and reference templates/snippets (vector/hybrid/image) plus agent-oriented examples (RAG/memory/text2sql).
22tidbx-serverless-driver
Guidance for using the TiDB Cloud Serverless Driver (Beta) in Node.js, serverless, and edge environments. Use when connecting to TiDB Cloud Starter/Essential over HTTP with @tidbcloud/serverless, or when integrating with Prisma/Kysely/Drizzle serverless adapters in Vercel/Cloudflare/Netlify/Deno/Bun. Use this skill for serverless driver setup and edge runtime guidance.
20tidbx
Provision TiDB Cloud Serverless clusters and related resources. Use when creating, deleting, or listing clusters/branches, or managing SQL users via the console.
18tidbx-kysely
Set up Kysely with TiDB Cloud (TiDB X), including @tidbcloud/kysely over the TiDB Cloud serverless HTTP driver for serverless or edge environments, plus standard TCP usage. Use for Kysely + TiDB Cloud connection setup, demo snippets, and environment-specific guidance.
17tidbx-javascript-mysql2
Connect to TiDB from JavaScript/Node.js using the mysql2 driver (mysql2/promise). Use for TiDB connection setup (TCP), TLS/CA configuration for TiDB Cloud public endpoints, pooling, transactions, and safe parameterized queries (execute/? placeholders) plus small runnable connection/CRUD templates.
16