TiDB · TiDB Cloud · TiDB Serverless

tidbchange

Existing tools treat TiDB as MySQL and call it done. tidbchange goes further — first-class HTAP governance that versions TiFlash replicas, placement policies, and resource groups natively in YAML, alongside SQL DDL migrations. Handles Serverless tier feature gaps with PARTIAL status tracking.

pip install tidbchange HTAP features →
0
Tools that version
TiFlash replicas as code
19
CLI capabilities
3
Cloud tiers
supported
tidbchange — HTAP deploy
# Deploy SQL + YAML migrations — polls TiFlash backfills
$ tidbchange deploy --profile prod --tag release-3.0
✓ V1.0.0__create_orders.sql   (1,102ms)
✓ V1.1.0__add_tiflash.yaml
    (TiFlash replicas: 2 → polling until ACTIVE)
    Replica progress: 78% (elapsed 12s)
    Replica ACTIVE — proceeding
✓ V1.2.0__resource_groups.yaml
    (OLTP: 5000 RU/s · OLAP: 2000 RU/s)
✓ V1.3.0__placement_policy.yaml
    (PRIMARY_REGION: us-east-1, FOLLOWERS: 2)
Deploy complete — 4 script(s) applied.
 
$
Works with TiDB v5.x+ TiDB v8.x TiDB Cloud Serverless TiDB Cloud Dedicated TiFlash GitHub Actions Claude Desktop MCP
HTAP Governance

Beyond SQL DDL.
First-class HTAP as code.

TiDB's HTAP model — TiFlash replicas, resource groups, and placement policies — is invisible to existing migration tools. tidbchange versions all of it alongside your SQL migrations, with polling, drift detection, and PARTIAL handling for Serverless tiers.

Key Differentiator
TiFlash replicas versioned and polled to completion
tidbchange versions TiFlash column-store replicas as code — per-table replica count in YAML, progress polling every 5 seconds until replicas are ACTIVE, and drift detection between YAML and the live cluster. Existing tools fire DDL and move on immediately, with no awareness of whether TiFlash replication is complete. tidbchange waits.
⚡
TiFlash Replica Lifecycle
Version TiFlash column-store replicas as code. Per-table replica count in YAML. Polls replication progress every 5s until ACTIVE before proceeding. Handles "already absent" idempotently on local.
KEY DIFFERENTIATOR
🎛️
Resource Group Versioning
OLTP/OLAP workload isolation via TiDB resource groups — RU/sec budgets, priority tiers, burstable flags — tracked, versioned, and drift-detected. PARTIAL status on Serverless where unsupported.
HTAP GOVERNANCE
🗺️
Placement Policy Lifecycle
Geographic data placement — PRIMARY_REGION, REGIONS list, FOLLOWERS — versioned in YAML and idempotent on re-deploy. PARTIAL on tiers that don't support placement.
DATA PLACEMENT
📋
SQL + YAML Hybrid Migrations
SQL for DDL, YAML for HTAP config. Both migrate in the same pipeline, share the same version numbering, and use the same history table. One tool, one audit log.
HYBRID
🔄
Drift Detection
Detect drift across tables, TiFlash replicas, resource groups, and placement policies — comparing YAML declarations against INFORMATION_SCHEMA live state.
DRIFT
🗃️
Separate History Database
Tracking tables live in a dedicated tidbchange schema, separate from your application database. Fully-qualified names prevent table confusion. History database is configurable per profile.
ARCHITECTURE
TiDB Cloud Support

Handles every
TiDB deployment.

From a local single-node to TiDB Cloud Serverless to Dedicated — tidbchange adapts. Features unavailable on a given tier are recorded as PARTIAL and automatically retried when capability exists.

LOCAL / SELF-MANAGED
TiDB v8.x
✓ SQL DDL migrations
✓ TiFlash replicas (if TiFlash nodes)
✓ Resource groups (v7.0+)
✓ Placement policies
✓ MySQL advisory locks
TIDB CLOUD SERVERLESS
TiDB Serverless
✓ SQL DDL migrations
✓ TiFlash (columnar storage built-in)
⚠ Resource groups — PARTIAL (not supported)
⚠ Placement policies — PARTIAL
✓ Automatic retry on capable tier
TIDB CLOUD DEDICATED
TiDB Dedicated
✓ Full feature support
✓ Resource groups
✓ Placement policies
✓ TiFlash replicas
✓ All YAML migration types
AI-Native Development

MCP Server.
AI Agents for TiDB.

tidbchange ships a Model Context Protocol server — letting Claude, Cursor, and any MCP-compatible AI assistant query your HTAP migration history, run drift detection, validate TiFlash and resource group YAML, and plan deployments without leaving the chat.

MCP Capabilities

What AI agents can do

Connect your AI assistant to tidbchange and unlock HTAP-aware conversations. Ask about TiFlash replica status, get resource group drift reports, validate placement policy YAML before running it, or generate new migration files from a natural language description of the workload isolation change you need.

Query migration history across SQL and YAML script types
Run drift detection across TiFlash replicas, resource groups, and placement policies
Validate SQL and YAML scripts offline without a TiDB connection
Generate scaffolded SQL + YAML migration pairs from natural language
Get pre-deploy TiFlash backfill risk and PARTIAL tier advisories
Inspect audit logs and compliance records
Ask "which tables lack TiFlash replicas in prod?" and get a structured answer
MCP Setup

One config. Any AI IDE.

The tidbchange MCP server exposes schema and HTAP tools through the standard Model Context Protocol. Works with Claude Desktop, Cursor, Windsurf, and any editor with MCP support. Your TiDB credentials stay local — the MCP server reads your existing tidbchange profiles.

# Claude Desktop — mcpServers config
"mcpServers": {
  "tidbchange": {
    "command": "tidbchange-mcp",
    "env": {"TIDB_PROFILE": "prod"}
  }
}
◑ Available
tidbchange MCP
TiDB · TiDB Cloud · TiDB Serverless
CLI Capabilities

19 Capabilities.
Same contract as every Schemashifts tool.

Every operation follows the same --profile flag, --dry-run support, and JSON output contract. PARTIAL scripts appear gracefully in status and are retried on the next deploy.

deploy
Apply SQL and YAML pending migrations. Polls TiFlash backfills until replicas are ACTIVE. PARTIAL for unsupported tier features. Use --dry-run to preview without touching TiDB.
rollback
Undo applied migrations by version or release tag using paired undo scripts. Reverses TiFlash, resource group, and placement policy changes in correct sequence.
validate
Offline SQL + YAML linting — no TiDB connection required. Catches syntax errors, missing undo scripts, TiFlash config errors, and version conflicts before CI runs.
status
Full migration history with timestamps, checksums, tags, and PARTIAL status tracking. Shows which scripts were skipped on Serverless and which are retried on Dedicated.
Drift detection
Detect drift across tables, TiFlash replicas, resource groups, and placement policies — comparing YAML declarations against INFORMATION_SCHEMA. Exits 1 on ERROR-severity findings.
Schema analysis
12 HTAP-aware rules — TiFlash replica gaps on OLAP-heavy tables, resource group isolation mismatches, stale table statistics, and placement policy inconsistencies.
Policy contracts
Policy-as-code enforcement — require TiFlash replicas on analytics tables, enforce resource group assignments, block OLAP workloads without isolation. Run in CI to gate non-compliant schema changes.
Baseline generation
Introspect a live TiDB instance and generate a V0.0.0 SQL + YAML baseline including TiFlash replica state, placement policies, and resource group configuration.
Test data seeding
Seed with TiDB-aware column handling — AUTO_RANDOM detection via COLUMN_TYPE, correct column length respect, and support for both TiKV and TiFlash storage engines.
Multi-tier pipeline
Deploy to multiple TiDB instances (local → Serverless → Dedicated) in order with per-stage confirmation gates and configurable failure handling.
Installation

Get started in
two minutes.

$ pip install tidbchange
Python 3.9+ · PyMySQL · pyyaml · TiDB 5.x+
# Then: tidbchange validate  ·  tidbchange deploy --profile local --dry-run