CockroachDB Migration 2026 — check your sql for free

6 findings in one CockroachDB orders.sql: that is what a YugabyteDB migration check returned for the schema a platform team exports first when it leaves self-hosted CockroachDB.

What Cockroach Labs changed, and when

Cockroach Labs retired the free CockroachDB Core edition with version 24.3.0 on 2024-11-18. Its Licensing FAQ says the CockroachDB Software License covers all versions from the 24.3.0 release date on, including patch fixes for 23.1 to 24.2 from that date. A cluster without a licence key gets a 7-day grace period, then is throttled to 5 concurrent open SQL transactions. Enterprise Free is for businesses with less than 10 million dollars in annual revenue, and Enterprise Free and Trial clusters are throttled after 7 days without sending telemetry. The Enterprise Trial lasts 30 days.

YugabyteDB is Apache-2.0 and speaks the PostgreSQL dialect, YSQL. CockroachDB also calls itself PostgreSQL-compatible, so the schema looks portable until the first CREATE TABLE runs.

The file

SET CLUSTER SETTING diagnostics.reporting.enabled = false;

CREATE TABLE orders (
  id INT PRIMARY KEY DEFAULT unique_rowid(),
  customer_id UUID NOT NULL,
  status STRING NOT NULL DEFAULT 'new',
  total DECIMAL(12,2) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  INDEX orders_customer_idx (customer_id)
);

UPSERT INTO orders (id, customer_id, status, total) VALUES (...);

The 6 findings

1. diagnostics.reporting.enabled = false (licence-telemetry-off). On Enterprise Free this is the setting that gets a cluster throttled after 7 days. On YugabyteDB, delete it.
2. INT (int-width). CockroachDB INT is 64-bit. YSQL INT is 32-bit, so ids above 2,147,483,647 overflow after the move. Write BIGINT.
3. unique_rowid() (unique-rowid). A CockroachDB built-in with no YSQL equivalent. Use BIGINT GENERATED BY DEFAULT AS IDENTITY.
4. STRING (string-type). A CockroachDB alias. Write TEXT.
5. INDEX orders_customer_idx (customer_id) inside CREATE TABLE (inline-index). YSQL rejects it. Move it to CREATE INDEX ... ON orders (customer_id).
6. UPSERT INTO (upsert). Not in YSQL. Write INSERT ... ON CONFLICT (id) DO UPDATE SET ....

The rewritten file, with PRIMARY KEY (id HASH) and INCLUDE (status) on the index, returns 0 findings.

Why a PostgreSQL linter does not catch it

Finding 2 is the dangerous one. INT is perfectly valid PostgreSQL, so a generic linter passes it. It fails later, when an id crosses the 32-bit limit. Findings 3 to 6 fail loudly, but without the rewrite.

What the 25 rules cover

The extension groups its 25 rules into licence and settings (4), types and keys (5), DDL (10) and DML and operations (6). Beyond the six above it flags hash-sharded indexes with bucket_count, column families, INVERTED INDEX (use GIN), STORING (use INCLUDE), CONFIGURE ZONE and multi-region LOCALITY (use tablespaces with replica placement), AS OF SYSTEM TIME, CREATE CHANGEFEED, crdb_internal and BACKUP/RESTORE.

Try it on your own file

Open any .sql file in VS Code and the findings land in the Problems panel, each ending with the YSQL rewrite. The same engine runs on the web page at getreadystack.com/tools/yugabytedb-migration-check, in the browser, with nothing uploaded. Checking one file is free and complete. The full version scans every migration in the workspace at once and exports a Markdown report for the change ticket.