15. When to use it

The previous fourteen chapters explained how it works. This one is about whether you should run it, and it is written to talk you out of it wherever that is the right outcome.

The question

Not “is CockroachDB good?” — it is very good at what it does. The question is:

Do you have a requirement that a single PostgreSQL with replicas genuinely cannot meet?

Most teams reaching for distributed SQL do not, and the cost of finding that out afterwards is high: higher write latency on every statement, retry handling in application code, a schema whose primary keys are placement decisions, and an operational surface far larger than one database with a standby.

Three requirements pass that test.

   ① DOWNTIME IS NOT ACCEPTABLE, INCLUDING FAILOVER
      not "we want high availability" — everyone wants
      that — but "a 90-second promotion is a business
      event, and we will not do them"

   ② DATA RESIDENCY, WITH ONE SCHEMA
      rows must live in particular countries, and you
      refuse to run one database per jurisdiction

   ③ WRITE VOLUME BEYOND ONE MACHINE
      genuinely beyond — after the obvious work on
      indexes, batching, and buying a bigger machine

If none applies, chapter 1’s comparison table is not advice you need. Run PostgreSQL.

The comparisons

Against PostgreSQL

   PostgreSQL wins on
     • write latency (sub-ms vs several ms)
     • maturity of the planner and the extension
       ecosystem: PostGIS, pgvector, timescale, …
     • operational familiarity; every engineer has
       met it, every tool supports it
     • cost, at any scale a single machine serves

   CockroachDB wins on
     • no failover, ever
     • horizontal write scale without a shard key
     • geographic row homing
     • survival of a whole region

The honest framing: PostgreSQL with a good standby covers an enormous range of businesses, and modern hardware moves the ceiling further every year. Choose the distributed system when the shape of the requirement is distributed, not when the size of the data feels impressive.

Against Vitess / Citus

Both add sharding to an existing database (MySQL, PostgreSQL) while keeping its engine.

   They win when
     • you already run that database at scale and the
       team knows it deeply
     • your workload shards cleanly on one key and
       cross-shard transactions are rare
     • you want the original engine's performance
       and ecosystem

   CockroachDB wins when
     • cross-shard transactions are normal, not rare
     • you cannot pick a shard key you will never
       want to change
     • you want failure tolerance rather than only
       capacity

Against Spanner

Spanner is the original and, with TrueTime, has an advantage CockroachDB cannot copy on rented hardware. It is also Google Cloud only.

   Spanner when      you are on GCP, want it managed,
                     and the pricing works for you
   CockroachDB when  you need to run anywhere — on-prem,
                     multi-cloud, another provider, or
                     self-managed by choice

Against Yugabyte / TiDB

Genuinely similar products. Yugabyte reuses PostgreSQL’s actual query layer, which buys compatibility depth; TiDB speaks MySQL and pairs an HTAP columnar engine with its row store. Differences are real but narrower than the marketing suggests, and the deciding factors are usually your dialect, your cloud, your support arrangement and a benchmark of your workload.

Against DynamoDB / Cassandra

   Choose the key-value store when
     • access is genuinely by one key
     • you do not need cross-item transactions
     • you want predictable cost and effectively
       unbounded scale

   Choose CockroachDB when
     • you need joins, foreign keys, secondary indexes
       and multi-row transactions — that is, when your
       data is relational and pretending otherwise
       would push the work into your application

Cassandra’s chapter 15 makes the same argument from the other side, and the two are consistent: the question is whether your access pattern is genuinely a single key.

Where compatibility ends

“PostgreSQL compatible” means the wire protocol and most of the dialect. Plan for these:

   • NO PostgreSQL EXTENSIONS. no PostGIS (there is
     built-in spatial, which is not the same), no
     pgvector, no pg_stat_statements, no pg_cron
   • triggers, stored procedures and some PL/pgSQL
     features arrived late or partially — verify
     against the release notes, not your memory
   • the planner is different, so plans and their
     regressions differ
   • sequences work but are a hotspot by nature
   • some catalog/system-view behaviour differs, which
     breaks tools that introspect deeply

Caution

The migration trap is not the syntax; it is the habits. BIGSERIAL primary keys, long interactive transactions, unbatched deletes, relying on SERIALIZABLE never aborting — all fine in PostgreSQL, all expensive here. A lift-and-shift that compiles is not a migration that performs.

The four ways it is misused

As a faster PostgreSQL. It is not, and will not be. Every write pays for consensus.

As an analytics database. Wide aggregations over hundreds of millions of rows are slow and expensive here. Stream to ClickHouse or DuckDB with a changefeed (chapter 12).

As a single-node database. Running one node “for now” gives you all the costs and none of the benefits.

As insurance against a scale that never arrives. The complexity is paid daily; the benefit arrives only if the requirement does. Regions and nodes can be added later — that is precisely why you do not need to pre-buy them.

Where it is uniquely right

   • a global SaaS product whose customers must be
     served locally and stored locally, in one schema
   • financial or ledger systems that need real
     serializability and cannot schedule downtime
   • a platform team replacing a fleet of sharded
     databases and their bespoke coordination code
   • anyone whose failover runbook has failed them
     once already, expensively

In those cases nothing else in this collection does the job, and the latency and complexity are simply the price.

What it costs

Money is part of the decision, and the shape of the cost is unusual enough to state plainly.

   HARDWARE       3 nodes minimum for any real
                  deployment, 6–9 for multi-region with
                  zone diversity. Replication factor 3
                  means 1 TB of data occupies 3 TB.

   LICENCE        free below a revenue threshold, paid
                  above it. Check the current terms —
                  they have changed twice.

   MANAGED        CockroachDB Cloud removes the
                  operational work and adds a per-hour
                  or per-request bill. For small teams
                  this is usually cheaper than the
                  engineer-hours it replaces.

   PEOPLE         the real cost. Someone must understand
                  ranges, leases, localities and retry
                  semantics well enough to debug them
                  under pressure.

That last row decides more adoptions than the others. A single PostgreSQL is understood by everyone you will ever hire.

If you do migrate

A checklist distilled from the previous fourteen chapters, in the order the work actually happens:

   □ primary keys: no monotonic leading columns
     (ch 3, 10) — this is a schema change, do it first
   □ pick the access dimension to lead composite keys
     (tenant_id, id) for locality
   □ retry loop for SQLSTATE 40001 in the data layer,
     not sprinkled through business logic (ch 5)
   □ shorten transactions; no network calls inside one
   □ batch large deletes, or adopt row-level TTL
   □ replace sequences with UUIDs or unique_rowid()
   □ covering indexes for hot queries (STORING)
   □ disallow_full_table_scans on in session defaults
   □ ANALYZE after the bulk load, before benchmarking
   □ gc.ttlseconds sized for backups and changefeeds
   □ localities set correctly on every node
   □ a restore, actually tested, before go-live

Benchmark after the first three, not before. A lift-and-shift benchmark measures your PostgreSQL habits, not this database.

The argument in one paragraph

CockroachDB buys you a database that does not need to be rescued: no promotion, no shard key, no region-per-jurisdiction sprawl. It charges for that in milliseconds on every write, in retry handling in your code, and in a schema that is also a placement plan. If your business genuinely cannot tolerate failover, or your rows genuinely must live in specific countries, that is a good trade and there are few alternatives. If you are choosing it because your data might get big, you are paying a daily cost for an event that may never come — and PostgreSQL will carry you much further than the marketing of distributed systems suggests.

What to take from this chapter

• The real question is whether a single PostgreSQL with replicas genuinely cannot meet the requirement. Usually it can.
• The three requirements that justify it: failover is unacceptable, per-row data residency in one schema, and write volume genuinely past one machine.
• Against Vitess/Citus: choose those when the workload shards cleanly and cross-shard transactions are rare; choose this when they are not.
• Against Spanner: Spanner has TrueTime and Google Cloud; this runs anywhere. Against Yugabyte/TiDB: genuinely close — decide on dialect, cloud, support, and a benchmark of your workload.
• Against DynamoDB/Cassandra: the question is whether access is genuinely by one key. If your data is relational, doing relational work in the application is the more expensive path.
• Compatibility ends at extensions and habits. No PostGIS or pgvector, a different planner, and PostgreSQL instincts — BIGSERIAL, long transactions, unbatched deletes — that are actively costly here.
• Four misuses: as a faster PostgreSQL, as an analytics engine, as a single node, and as insurance against a scale that never arrives.
• It is uniquely right for global SaaS with residency requirements, ledger systems that cannot schedule downtime, and teams retiring a sharded fleet.

Next: the cheat sheet — every command, setting, error and threshold from this guide on one page.