Teaching AI Agents to Speak “Production” SQL: Introducing TiDB Skills

AI coding agents are excellent at producing code that “works on my machine”. But as every database engineer knows, there is a massive gap between a query that runs in a local Docker container and one that survives in a high-concurrency production environment.

We keep seeing the same issues arise when agents generate SQL based on generic tutorials:

• “Looks fine” queries that explode at scale because the plan is wrong (and nobody checked EXPLAIN.
• Insecure connections caused by incomplete TLS verification settings.
• Transaction bugs where the app assumes InnoDB-like defaults, but the distributed engine is running in a different mode.
• Compatibility pitfalls where features exist in MySQL but behave differently in distributed systems.

Most database incidents aren’t caused by missing syntax; they’re caused by missing context.

That is whywe are introducing pingcap/agent-rules: TiDB Skills. It is a 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.

How It Works

We 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.

The repo is structured to allow agents to retrieve only the context they need, keeping the prompt window efficient:

The workflow is designed to be simple and invisible to the user:

1. Select: The agent selects the relevant skill folder (e.g., skills/tidb-sql when generating SQL).
2. Retrieve: It pulls in only the reference it needs for the specific task (e.g., transactions.md when working on multi-step writes).
3. Apply: It applies the guidance as constraints while generating code, rather than relying on “best effort” guesses.

Deep Dive: The Gap Between “Generic” and “Production”

To see the difference this makes, let’s look at two specific examples where generic SQL generation fails in production.

1. The Transaction Trap

Without the tidb-sql skill, an agent simply writes BEGIN, implicitly assuming pessimistic locking. With the skill, the agent is forced to make a conscious choice between modes.

The Rule (from transactions.md):

“Prefer pessimistic when conflicts are common… Consider optimistic when write-write conflicts are rare and you can handle commit failures in the app.”

The Agent’s Output: By consuming this rule, the agent understands that if it chooses Optimistic mode, it must also generate the application-level retry loop. It stops treating COMMIT as a guaranteed success.

-- The agent now explicitly declares the mode [cite: 64]
BEGIN PESSIMISTIC;
-- ... DML ...
COMMIT;

2. The Primary Key Hotspot

Agents trained on MySQL tutorials love AUTO_INCREMENT. 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.

The Rule (from hotspots.md):

“Hotspot Avoidance / ID Strategy (Medium-High): when and how to use AUTO_RANDOM.”

The Agent’s Output: Instead of the generic default, the agent generates a schema optimized for correctness at scale:

CREATE TABLE users (
  -- Agent switches to AUTO_RANDOM for distribution 
  id BIGINT PRIMARY KEY AUTO_RANDOM, 
  email VARCHAR(255) NOT NULL,
  ...
);

The Toolkit: What’s Included

The 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.

1. Safety & Correctness (Critical)

These skills focus on preventing data loss and connection failures:

• TLS and Connection Safety: Enforces strict SSL verification requirements and client configuration patterns to prevent flaky or insecure connections.
• Transactions and Concurrency: This is one of the most common pitfalls. The skill clarifies optimistic vs. pessimistic transactions, how to handle commit failures, and when to use session vs. global knobs.

2. Performance & Scale (High Signal)

Agents often write schema without considering distributed performance. These skills guide them toward scalable patterns:

• Hotspot Avoidance / ID Strategy: Teaches the agent when and how to use AUTO_RANDOM instead of AUTO_INCREMENT to avoid write hotspots on primary keys.
• Query Plans and Diagnostics: Instructs the agent on how to use EXPLAIN and EXPLAIN ANALYZE to verify performance, and when to refresh statistics.
• Compatibility Pitfalls: Flags common constructs that “work on MySQL but break on TiDB”.

3. Advanced Features

We also cover advanced features that require specific DDL or availability checks:

• Vector Search: Provides correct patterns for VECTOR types, vector functions, and vector index DDL.
• Recovery Playbooks: Syntax for flashback-based recovery workflows,including FLASHBACK TABLE/DATABASE.
• Full-Text Search: Specific SQL patterns and availability gotchas for TiDB’s implementation of full-text search.

4. Application Integration (Drivers & ORMs)

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.

• Node.js: tidbx-javascript-mysql2 for standard pooling/TLS, and tidbx-javascript-mysqljs for legacy codebases.
• TypeScript/ORM: tidbx-kysely and tidbx-prisma for typed SQL, schema management, and correct DATABASE_URL TLS parameters.
• Serverless/Edge: tidbx-serverless-driver guidance for HTTP-based connectivity in edge runtimes where TCP is not an option.
• Python: pytidb guidance for CRUD, vector search, and hybrid search integration.

Install in Your Agent

The repo is available at pingcap/agent-rules. You can install these skills directly into your agent’s configuration using Vercel’s skills package.

Run the following command in your terminal. It will prompt you to choose the skills you want and which agent you are using (Claude Code, Codex, Cursor, etc.):

npxskillsaddpingcap/agent-rules

Once installed, your agent will automatically pick the right skill at the right time—you usually do not need to think about “which skill to use”.

FAQ

Q: Does this work for standard MySQL? A: Many skills (like TLS safety, EXPLAIN checks, and safe parameterization) are universal best practices for any MySQL environment. However, distributed features like AUTO_RANDOM or specific transaction modes are optimized for TiDB and may require adjustment for single-node MySQL.

Q: Do I need to manually trigger these skills? A: No. Once installed via the skills CLI, agents like Claude Code or Cursor will automatically detect the context (e.g., when you ask to “write a schema for TiDB”) and retrieve the relevant rules before generating code.

Q: Does this replace code review? A: No. Think of TiDB Skills as a “guardrail” or a linter that runs during generation. It catches common “junior engineer” mistakes (like missing TLS or hotspots) early, but production changes should always go through human review.

Wrap Up

These skills are not a replacement for code review or security policies, but they act as a “guardrail” to prevent common foot-guns. They give your AI agents the missing context to warn you early, generate safer defaults, and produce SQL that is likely to survive production.

If you run into a MySQL/TiDB “gotcha” that isn’t covered yet, open an issue or PR in pingcap/agent-rules so the next agent run gets it right by default.