> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Tables

In a [multi-region deployment](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality), [`GLOBAL` table locality](https://docs.cockroachlabs.com/docs/stable/table-localities#global-tables) is a good choice for tables with the following requirements:

* Read latency must be low, but write latency can be much higher.
* Reads must be up-to-date for business reasons or because the table is referenced by [foreign keys](https://docs.cockroachlabs.com/docs/stable/foreign-key.md).
* Rows in the table, and all latency-sensitive reads, **cannot** be tied to specific regions.

In general, this pattern is suited well for reference tables that are rarely updated.

Tables with the `GLOBAL` locality can survive zone or region failures, depending on the database-level [survival goal](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#survival-goals) setting.

For new clusters using the [multi-region SQL abstractions](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality), Cockroach Labs recommends lowering the [`--max-offset`](https://docs.cockroachlabs.com/docs/stable/cockroach-start#flags-max-offset) setting to `250ms`. This setting is especially helpful for lowering the write latency of [global tables](https://docs.cockroachlabs.com/docs/stable/table-localities.md#global-tables). Nodes can run with different values for `--max-offset`, but only for the purpose of updating the setting across the cluster using a rolling upgrade.

## Before you begin

### Fundamentals

Multi-region patterns require thinking about the following questions:

* What are your [survival goals](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#survival-goals)?  Do you need to survive a [zone failure](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals.md#survive-zone-failures)? Do you need to survive a [region failure](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals.md#survive-region-failures)?
* What are the [table localities](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality) that will provide the performance characteristics you need for each table's data?
  * Do you need low-latency reads and writes from a single region? Do you need that single region to be configurable at the [row level](https://docs.cockroachlabs.com/docs/stable/table-localities.md#regional-by-row-tables)? Or will [a single optimized region for the entire table](https://docs.cockroachlabs.com/docs/stable/table-localities.md#regional-tables) suffice?
  * Do you have a "read-mostly" [table of reference data that is rarely updated](https://docs.cockroachlabs.com/docs/stable/table-localities.md#global-tables), but that must be read with low latency from all regions?

For more information about CockroachDB multi-region capabilities, review the following pages:

* [Multi-Region Capabilities Overview](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality)
* [How to Choose a Multi-Region Configuration](https://docs.cockroachlabs.com/docs/stable/choosing-a-multi-region-configuration.md)
* [When to use `ZONE` vs. `REGION` Survival Goals](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals#when-to-use-zone-vs-region-survival-goals)
* [When to use `REGIONAL` vs. `GLOBAL` Tables](https://docs.cockroachlabs.com/docs/stable/table-localities#when-to-use-regional-vs-global-tables)

In addition, reviewing the following information will be helpful:

* The concept of [locality](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md#locality), which CockroachDB uses to place and balance data based on how you define survival goal and table locality settings.
* The recommendations in our [Production Checklist](https://docs.cockroachlabs.com/docs/stable/recommended-production-settings.md), including our [hardware recommendations](https://docs.cockroachlabs.com/docs/stable/recommended-production-settings.md#hardware). Afterwards, perform a proof of concept to size hardware for your use case.
* [SQL Performance Best Practices](https://docs.cockroachlabs.com/docs/stable/performance-best-practices-overview.md)

### Cluster setup

Each [multi-region pattern](https://docs.cockroachlabs.com/docs/stable/topology-patterns.md#multi-region) assumes the following setup:

![Multi-region hardware setup](https://mintcdn.com/cockroachlabs/iiBVxthghoAOO3UM/images/common/topology-patterns/topology_multi-region_hardware.png?fit=max\&auto=format\&n=iiBVxthghoAOO3UM\&q=85\&s=810cffba5f7294be67bc34e0b3276c28)

#### Hardware

* 3 regions
* Per region, 3+ AZs with 3+ VMs evenly distributed across them
* Region-specific app instances and load balancers
  * Each load balancer redirects to CockroachDB nodes in its region.
  * When CockroachDB nodes are unavailable in a region, the load balancer redirects to nodes in other regions.

#### Cluster startup

Start each node with the [`--locality`](https://docs.cockroachlabs.com/docs/stable/cockroach-start#locality) flag specifying its region and AZ combination. For example, the following command starts a node in the `west1` AZ of the `us-west` region:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach start \
--locality=region=us-west,zone=west1 \
--certs-dir=certs \
--advertise-addr=<node1 internal address \
--join=<node1 internal address:26257,<node2 internal address:26257,<node3 internal address:26257 \
--cache=.25 \
--max-sql-memory=.25 \
--background
```

## Configuration

### Summary

To use this pattern, set the [table locality](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality) to `GLOBAL`.

A *global* table is optimized for low-latency reads from every region in the database. This means that any region can effectively act as the home region of the table. The tradeoff is that writes will incur higher latencies from any given region, since writes have to be replicated across every region to make the global low-latency reads possible. Use global tables when your application has a "read-mostly" table of reference data that is rarely updated, and needs to be available to all regions.

For an example of a table that can benefit from the *global* table locality setting in a multi-region deployment, see the `promo_codes` table from the [MovR application](https://docs.cockroachlabs.com/docs/stable/movr.md).

For instructions showing how to set a table's locality to `GLOBAL`, see [`ALTER TABLE ... SET LOCALITY`](https://docs.cockroachlabs.com/docs/stable/alter-table#global).

For more information about global tables, including troubleshooting information, see [Global Tables](https://docs.cockroachlabs.com/docs/stable/global-tables.md).

### Steps

1. Create a database and set it as the default database:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE DATABASE test;
   ```

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   USE test;
   ```

   [This cluster is already deployed across three regions](#cluster-setup). Therefore, to make this database a "multi-region database", issue the following SQL statement to [set the primary region](https://docs.cockroachlabs.com/docs/stable/alter-database.md#set-the-primary-region):

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ALTER DATABASE test PRIMARY REGION "us-east";
   ```

> [!NOTE]
>
> Every multi-region database must have a primary region.  For more information, see [Database regions](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#database-regions).

1. Issue the following [`ADD REGION`](https://docs.cockroachlabs.com/docs/stable/alter-database#add-region) statements to add the remaining regions to the database:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ALTER DATABASE test ADD REGION "us-west";
   ```

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ALTER DATABASE test ADD REGION "us-central";
   ```

2. Create a [`GLOBAL` table](https://docs.cockroachlabs.com/docs/stable/table-localities#global-tables) by issuing the following statement:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE TABLE postal_codes (
     id INT PRIMARY KEY,
     code STRING
   ) LOCALITY GLOBAL;
   ```

   Alternatively, you can set an existing table's locality to `GLOBAL` using [`ALTER TABLE ... SET LOCALITY`](https://docs.cockroachlabs.com/docs/stable/alter-table#set-locality):

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   > ALTER TABLE postal_codes SET LOCALITY GLOBAL;
   ```

> [!TIP]
>
> A good way to check that your [table locality settings](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster.

## Characteristics

### Latency

Global tables support low-latency, global reads of read-mostly data using an extension to CockroachDB's standard transaction protocol called [non-blocking transactions](https://docs.cockroachlabs.com/docs/stable/architecture/transaction-layer.md#non-blocking-transactions).

#### Reads

Thanks to the [non-blocking transaction](https://docs.cockroachlabs.com/docs/stable/architecture/transaction-layer.md#non-blocking-transactions) protocol extension, reads against `GLOBAL` tables access a consistent local replica and therefore never leave the region. This keeps read latency low.

#### Writes

Writes incur higher latencies than reads, since they require a "commit-wait" step to ensure consistency. For more information about how this works, see [non-blocking transactions](https://docs.cockroachlabs.com/docs/stable/architecture/transaction-layer.md#non-blocking-transactions).

### Resiliency

Because the `test` database does not specify a [survival goal](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#survival-goals), it uses the default [`ZONE` survival goal](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals#survive-zone-failures). With the default settings, an entire zone can fail without interrupting access to the database.

For more information about how to choose a database survival goal, see [When to Use `ZONE` vs. `REGION` Survival Goals](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals#when-to-use-zone-vs-region-survival-goals).

## Troubleshooting

### High follower read latency on global tables

Reads on multi-region global tables can experience sporadic high latency on [follower reads](https://docs.cockroachlabs.com/docs/stable/follower-reads.md) if the round trip time between cluster nodes is higher than 150ms. To work around this issue, consider setting the `kv.closed_timestamp.lead_for_global_reads_override` [cluster setting](https://docs.cockroachlabs.com/docs/stable/cluster-settings.md) to a value greater than 800ms.

The value of `kv.closed_timestamp.lead_for_global_reads_override` will impact write latency to global tables, so you should proceed in 100ms increments until the high read latency no longer occurs. If you've increased the setting to 1500ms and the problem persists, you should [contact support](https://docs.cockroachlabs.com/docs/stable/support-resources.md).

## Alternatives

* If rows in the table, and all latency-sensitive queries, can be tied to specific geographies, consider the [`REGIONAL` Table Locality Pattern](https://docs.cockroachlabs.com/docs/stable/regional-tables) pattern.

## See also

* [Multi-Region Capabilities Overview](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality)
* [How to Choose a Multi-Region Configuration](https://docs.cockroachlabs.com/docs/stable/choosing-a-multi-region-configuration.md)
* [When to Use `ZONE` vs. `REGION` Survival Goals](https://docs.cockroachlabs.com/docs/stable/multiregion-survival-goals#when-to-use-zone-vs-region-survival-goals)
* [When to Use `REGIONAL` vs. `GLOBAL` Tables](https://docs.cockroachlabs.com/docs/stable/table-localities#when-to-use-regional-vs-global-tables)
* [Secondary regions](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#secondary-regions)
* [`ALTER DATABASE ... SET SECONDARY REGION`](https://docs.cockroachlabs.com/docs/stable/alter-database#set-secondary-region)
* [`ALTER DATABASE ... DROP SECONDARY REGION`](https://docs.cockroachlabs.com/docs/stable/alter-database#drop-secondary-region)
* [Topology Patterns Overview](https://docs.cockroachlabs.com/docs/stable/topology-patterns.md)
  * Single-region patterns
    * [Basic Production](https://docs.cockroachlabs.com/docs/stable/topology-basic-production.md)
  * Multi-region patterns
    * [`REGIONAL` Tables](https://docs.cockroachlabs.com/docs/stable/regional-tables)
    * [`GLOBAL` Tables](https://docs.cockroachlabs.com/docs/stable/global-tables)
    * [Follower Reads](https://docs.cockroachlabs.com/docs/stable/topology-follower-reads.md)
    * [Follow-the-Workload](https://docs.cockroachlabs.com/docs/stable/topology-follow-the-workload.md)