When to Use REGIONAL vs. GLOBAL Tables

CockroachDB v22.1 is no longer supported as of November 24, 2023. For more details, refer to the Release Support Policy.

A table locality indicates how CockroachDB optimizes access to a table's data in a multi-region cluster. CockroachDB uses the table locality setting to determine how to optimize access to the table's data from that locality.


This is an enterprise-only feature. Request a 30-day trial license to try it out.

The following table localities are available:


Use a REGIONAL table locality if:

  • Your application requires low-latency reads and writes from a single region (either at the row level or the table level).
  • Access to the table's data can be slower (higher latency) from other regions.

Use a GLOBAL table locality if:

  • Your application has a "read-mostly" table of reference data that is rarely updated, and that needs to be available to all regions.
  • You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future". Note that the observed write latency is dependent on the --max-offset setting.

For new clusters using the multi-region SQL abstractions, Cockroach Labs recommends lowering the --max-offset setting to 250ms. This setting is especially helpful for lowering the write latency of global tables. For existing clusters, changing the setting will require restarting all of the nodes in your cluster at the same time; it cannot be done with a rolling restart.

See also

Yes No