EXPLAIN<\/code><\/a>.<\/li>\n\n\n\n- Insecure connections<\/strong> caused by incomplete TLS verification settings.<\/li>\n\n\n\n
- Transaction<\/strong> bugs<\/strong> where the app assumes InnoDB-like defaults, but the distributed engine is running in a different mode.<\/li>\n\n\n\n
- Compatibility pitfalls<\/strong> where features exist in MySQL but behave differently in distributed systems.<\/li>\n<\/ul>\n\n\n\n
Most database incidents aren’t caused by missing syntax; they’re caused by missing context<\/strong>.<\/p>\n\n\n\nThat is why we are introducing TiDB Skills<\/a><\/strong>, a GitHub repository of machine-readable context that agents (like Claude Code, Cursor, or Codex) can retrieve at write-time to generate safer, production-grade SQL for TiDB Cloud<\/a>.<\/strong><\/p>\n\n\n\n<\/span>How TiDB Skills Works<\/span><\/h2>\n\n\n\nWe packaged these operational “gotchas” into small, machine-readable skill folders. This allows agents to reliably look up the right rules at the moment they’re writing SQL, reviewing a migration, or troubleshooting a production issue.<\/p>\n\n\n\n
The repo is structured to allow agents to retrieve only<\/em> the context they need, keeping the prompt window efficient:<\/p>\n\n\n\n![\"\"](\"https:\/\/static.pingcap.com\/files\/2026\/02\/03003552\/tidb-skills.png\")
<\/figure>\n\n\n\nThe workflow is designed to be simple and invisible to the user:<\/p>\n\n\n\n
\n- Select<\/strong>: The agent selects the relevant skill folder (e.g.,
skills\/tidb-sql<\/code> when generating SQL).<\/li>\n\n\n\n- Retrieve<\/strong>: It pulls in only the reference it needs for the specific task (e.g.,
transactions.md<\/code> when working on multi-step writes).<\/li>\n\n\n\n- Apply<\/strong>: It applies the guidance as constraints while generating code, rather than relying on “best effort” guesses.<\/li>\n<\/ol>\n\n\n\n
<\/span>Deep Dive: The Gap Between “Generic” and “Production”<\/span><\/h2>\n\n\n\nTo see the difference this makes, let’s look at two specific examples where generic SQL generation fails in production.<\/p>\n\n\n\n
1<\/strong>. The Transaction Trap<\/strong><\/h3>\n\n\n\nWithout the tidb-sql<\/code> skill, an agent simply writes BEGIN<\/code>, implicitly assuming pessimistic locking. With the skill, the agent is forced to make a conscious choice between modes.<\/p>\n\n\n\nThe Rule (from transactions.md<\/code>):<\/strong> “Prefer pessimistic<\/strong> when conflicts are common… Consider optimistic<\/strong> when write-write conflicts are rare and you can handle commit failures in the app.”<\/p>\n\n\n\nThe Agent’s Output:<\/strong> By consuming this rule, the agent understands that if it chooses Optimistic mode, it must<\/em> also generate the application-level retry loop. It stops treating COMMIT<\/code> as a guaranteed success.<\/p>\n\n\n\n-- The agent now explicitly declares the mode [cite: 64]\nBEGIN PESSIMISTIC;\n-- ... DML ...\nCOMMIT;<\/code><\/pre>\n\n\n\n2<\/strong>. The Primary Key Hotspot<\/strong><\/h3>\n\n\n\nAgents trained on MySQL tutorials love AUTO_INCREMENT<\/code>. In a single-node database, this is fine. In a distributed system, sequentially increasing IDs cause all writes to hit a single region (a “hotspot”), killing write performance.<\/p>\n\n\n\nThe Rule (from hotspots.md<\/code>):<\/strong> “Hotspot Avoidance \/ ID Strategy (Medium-High): when and how to use AUTO_RANDOM.”<\/p>\n\n\n\nThe Agent’s Output:<\/strong> Instead of the generic default, the agent generates a schema optimized for correctness at scale:<\/p>\n\n\n\nCREATE TABLE users (\n -- Agent switches to AUTO_RANDOM for distribution \n id BIGINT PRIMARY KEY AUTO_RANDOM, \n email VARCHAR(255) NOT NULL,\n ...\n);<\/code><\/pre>\n\n\n\n<\/span>The Toolkit: What’s Included<\/span><\/h2>\n\n\n\nThe guidance is organized around a core SQL skill plus supporting connection and ORM skills. Here is the breakdown of the context we are injecting into the agents.<\/p>\n\n\n\n
1. <\/strong>Safety & Correctness (Critical)<\/h3>\n\n\n\nThese skills focus on preventing data loss and connection failures:<\/p>\n\n\n\n
\n- TLS and Connection Safety<\/a><\/strong>: Enforces strict SSL verification requirements and client configuration patterns to prevent flaky or insecure connections.<\/li>\n\n\n\n
- Transactions and Concurrency<\/a><\/strong>: This is one of the most common pitfalls. The skill clarifies optimistic vs. pessimistic<\/strong> transactions, how to handle commit failures, and when to use session vs. global knobs.<\/li>\n<\/ul>\n\n\n\n
2. Performance & Scale (High Signal)<\/h3>\n\n\n\n
Agents often write schema without considering distributed performance. These skills guide them toward scalable patterns:<\/p>\n\n\n\n
\n- Hotspot Avoidance \/ ID Strategy<\/strong>: Teaches the agent when and how to use
AUTO_RANDOM<\/code> instead of AUTO_INCREMENT<\/code> to avoid write hotspots on primary keys.<\/li>\n\n\n\n- Query Plans and Diagnostics<\/strong>: Instructs the agent on how to use
EXPLAIN<\/code><\/a> \uadf8\ub9ac\uace0 EXPLAIN ANALYZE<\/code> to verify performance, and when to refresh statistics.<\/li>\n\n\n\n- Compatibility Pitfalls<\/strong>: Flags common constructs that “work on MySQL but break on TiDB”.<\/li>\n<\/ul>\n\n\n\n
3. Advanced Features<\/h3>\n\n\n\n
We also cover advanced features that require specific DDL or availability checks:<\/p>\n\n\n\n
\n- Vector Search<\/strong>: Provides correct patterns for
VECTOR<\/code><\/a> types, vector functions, and vector index DDL.<\/li>\n\n\n\n- Recovery Playbooks<\/strong>: Syntax for flashback-based recovery workflows, including
FLASHBACK TABLE\/DATABASE<\/code><\/a>.<\/li>\n\n\n\n- Full-Text Search<\/strong>: Specific SQL patterns and availability gotchas for TiDB’s implementation of full-text search.<\/li>\n<\/ul>\n\n\n\n
4. Application Integration (Drivers & ORMs)<\/h3>\n\n\n\n
For application integration, we provide specific driver skills that cover pooling, safe parameterization, and TLS wiring. This ensures the “default Node.js driver” path is production-safe.<\/p>\n\n\n\n
\n- Node.js<\/strong>:
tidbx-javascript-mysql2<\/code> for standard pooling\/TLS, and tidbx-javascript-mysqljs<\/code> for legacy codebases.<\/li>\n\n\n\n- TypeScript\/ORM<\/strong>:
tidbx-kysely<\/code> \uadf8\ub9ac\uace0 tidbx-prisma<\/code> for typed SQL, schema management, and correct DATABASE_URL<\/code> TLS parameters.<\/li>\n\n\n\n- Serverless\/Edge<\/strong>:
tidbx-serverless-driver<\/code> guidance for HTTP-based connectivity in edge runtimes where TCP is not an option.<\/li>\n\n\n\n- Python<\/strong>:
pytidb<\/code> guidance for CRUD, vector search, and hybrid search integration.<\/li>\n<\/ul>\n\n\n\n<\/span>Install in Your Agent<\/span><\/h2>\n\n\n\n