CockroachDB · CockroachDB Cloud · v21.1+

cockroachchange

Most migration tools treat CockroachDB as PostgreSQL and stop there. cockroachchange goes further — it versions multi-region locality, survival goals, and zone configs as YAML, monitors DDL background jobs to completion, and handles schema-locked tables in CockroachDB v26.1.

pip install cockroachchange Multi-region features →

Tools that do multi-region
as code (before us)

CLI capabilities

CRDB-specific
analyser rules

cockroachchange — multi-region deploy

# Full multi-region deploy — SQL + YAML in one pipeline

$ cockroachchange deploy --profile local

✓ V1.0.0__create_core_tables.sql (1,242ms)

✓ V1.2.0__add_hash_sharded_index.sql (2,087ms)

Waiting for job 987654 to complete (CREATE INDEX, hash-sharded)...

✓ V1.3.0__add_multi_region.yaml

SET PRIMARY REGION us-east1 · ADD REGION us-west2 · ADD REGION eu-west1

SURVIVE REGION FAILURE

schema_locked=false on 'orders' · SET LOCALITY REGIONAL BY ROW · schema_locked=true

✓ V1.4.0__zone_configs.yaml (gc_ttl=90d applied)

✓ R__ensure_audit_index.sql

Works with CockroachDB 21.1+ CockroachDB Cloud CockroachDB v26.1 Multi-region clusters GitHub Actions MCP Server

Multi-Region as Code

The only tool that understands
CockroachDB topology.

Existing migration tools treat CockroachDB as Postgres. cockroachchange is the first migration tool to version multi-region locality, survival goals, and zone configs as first-class YAML — tracked, diffed, and rollback-ready.

Key Differentiator

Multi-region locality versioned as YAML

Primary region, additional regions, survival goal, and per-table locality (REGIONAL BY ROW, GLOBAL, REGIONAL BY TABLE) — all in a single versioned YAML file. cockroachchange applies the correct DDL sequence, handles schema-locks automatically, and records the full topology in migration history. No other tool does this.

# V1.3.0__add_multi_region.yaml
regions:
  primary: us-east1
  additional: [us-west2, eu-west1]
  survival_goal: REGION
tables:
  - table: orders
    locality: REGIONAL BY ROW  # crdb_region column auto-added
  - table: products
    locality: GLOBAL           # read from any region

🌍

Multi-Region YAML

Primary region, additional regions, survival goal, and per-table locality — all in one YAML file. Versioned, checksummed, and tracked.

TOPOLOGY AS CODE

🔒

Schema Lock Handling

CockroachDB v26.1 schema-locks tables by default. cockroachchange automatically unlocks before locality changes and re-locks after — without failing your deploy.

v26.1 COMPATIBLE

⚙️

Zone Config Lifecycle

GC TTL, lease preferences, replica constraints — applied with override_multi_region_zone_config automatically set. Understands what each tier supports.

ZONE CONFIGS

⏳

DDL Job Monitoring

CockroachDB runs DDL as background jobs. cockroachchange polls job status until terminal state — if a job fails, the migration fails. Existing tools have no awareness of CockroachDB background jobs at all.

KEY DIFFERENTIATOR

🔄

Serialization Retry

Handles CockroachDB 40001 serialization errors with exponential backoff. DDL conflicts that existing tools silently fail on are retried automatically.

RELIABILITY

📋

CRDB-Aware Analyser

8 CockroachDB-specific rules — missing region columns, unhashed primary keys on regional tables, missing GC TTL, and zone config anti-patterns.

ANALYSIS

AI-Native Development

MCP Server.
AI Agents for CockroachDB.

cockroachchange ships a Model Context Protocol server — letting Claude, Cursor, and any MCP-compatible AI assistant query your migration history, run drift detection, validate multi-region YAML, and understand your cluster topology without leaving the chat.

MCP Capabilities

What AI agents can do

Connect your AI assistant to cockroachchange and unlock topology-aware conversations. Ask about DDL job status, get multi-region drift reports, validate YAML locality configs before running them, or generate new migration files from a natural language description of the region change you need.

Query migration history and applied status per environment

Run drift detection across locality, survival goals, and zone configs

Validate multi-region YAML offline without a cluster connection

Generate scaffolded SQL + YAML migration pairs from natural language

Get pre-deploy DDL job risk advisories and schema-lock warnings

Inspect audit logs, compliance records, and operator history

Ask "what changed in the multi-region config last month?" and get a structured answer

MCP Setup

One config. Any AI IDE.

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

# Claude Desktop — mcpServers config
"mcpServers": {
  "cockroachchange": {
    "command": "cockroachchange-mcp",
    "env": {"CRDB_PROFILE": "prod"}
  }
}

◑ Available

cockroachchange MCP

CockroachDB · CockroachDB Cloud

CLI Capabilities

19 Capabilities.
One consistent interface.

Every operation follows the same --profile flag, --dry-run support, and JSON output contract. The same CLI you learn in dev works identically in prod.

deploy

Apply SQL and YAML pending migrations in semver order. Monitors DDL background jobs to completion. Handles schema locks automatically for v26.1. Use --dry-run to preview without touching the cluster.

rollback

Undo applied migrations by version or release tag using paired undo scripts. Reverses multi-region changes in correct order — locality first, then regions. Full audit record written.

validate

Offline validation — SQL parse, YAML structure, locality constraints, duplicate versions, orphan undo scripts. No cluster connection required. Exits 1 on any error — suitable as a CI gate.

status

Full migration history with timestamps, checksums, tags, and operator info. Shows what ran, what's pending, what was rolled back, and any PARTIAL statuses — sortable by tag or version.

Drift detection

Compare live CockroachDB schema against migration history. Detects locality changes, zone config drift, schema-lock state, and out-of-band DDL. Exits 1 on ERROR findings.

Schema analysis

8 CRDB-specific rules — unhashed PKs on regional tables, missing crdb_region columns, GC TTL gaps, zone config anti-patterns, and serialization retry coverage.

Policy contracts

Enforce policy-as-code governance rules — require survival goals on all multi-region tables, mandatory GC TTL, prohibited default localities. Block non-compliant changes in CI.

Baseline generation

Introspect a live CockroachDB cluster and generate a V0.0.0 baseline — captures SQL schema, multi-region configuration, zone configs, and locality settings.

Hash-sharded index scaffolding

Generate correct hash-sharded index migration scripts from a table name and key list. Includes the bucket_count and correct CockroachDB syntax — no guesswork.

Multi-region pipeline

Deploy to multiple clusters in order (dev → staging → prod) with per-stage confirmation gates, per-stage tag fences, and configurable failure handling: rollback, stop, or continue.

Comparison