> ## 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.

# Multi-Region Capabilities Overview

This page provides an overview of CockroachDB multi-region capabilities.

## Overview

CockroachDB multi-region capabilities make it easier to run global applications. To use these capabilities effectively, you should understand the following concepts:

* [*Cluster region*](#cluster-regions) is a geographic region that you specify at node start time.
* [*Database region*](#database-regions) is a geographic region in which a database operates. You must choose a database region from the list of available cluster regions.
* [*Survival goal*](#survival-goals) dictates how many simultaneous failure(s) a database can survive.
* [*Table locality*](#table-locality) determines how CockroachDB optimizes access to a table's data.

At a high level, the simplest process for running a multi-region cluster is:

1. Set region information for each node in the cluster at startup using [node startup locality options](/docs/stable/cockroach-start.md#locality).
2. Add one or more regions to a database, making it a "multi-region" database. One of these regions must be the *primary region*.
3. (*Optional*) Change table localities (global, regional by table, regional by row). This step is optional because by default the tables in a database will be homed in the database's primary region (as set during Step 1).
4. (*Optional*) Change the database's survival goals (zone or region). This step is optional because by default multi-region databases will be configured to survive zone failures.

These steps describe the simplest case, where you accept all of the default settings. The latter two steps are optional, but table locality and survival goals have a significant impact on performance. Therefore Cockroach Labs recommends that you give these aspects some consideration [when you choose a multi-region configuration](/docs/stable/choosing-a-multi-region-configuration.md).

For new clusters using the [multi-region SQL abstractions](/docs/stable/multiregion-overview.md), Cockroach Labs recommends lowering the [`--max-offset`](/docs/stable/cockroach-start#flags-max-offset) setting to `250ms`. This setting is especially helpful for lowering the write latency of [global tables](/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.

## Cluster regions

You define a cluster region at the node level using the `region` key and the zone using the `zone` key in the [node startup locality options](/docs/stable/cockroach-start.md#locality).

For example, the following command adds `us-east-1` to the list of cluster regions and `us-east-1b` to the list of zones:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach start --locality=region=us-east-1,zone=us-east-1b # ... other required flags go here
```

To show all of a cluster's regions, execute the following SQL statement:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SHOW REGIONS FROM CLUSTER;
```

## Database regions

A *database region* is a high-level abstraction for a geographic region. Each region is broken into multiple zones. These terms are meant to correspond directly to the region and zone terminology used by cloud providers.

The regions added during node startup become *database regions* when you add them to a database. To add the first region, use the [`ALTER DATABASE ... PRIMARY REGION` statement](/docs/stable/alter-database#set-primary-region).

While the database has only one region assigned to it, it is considered a "multi-region database."  This means that all data in that database is stored within its assigned regions, and CockroachDB optimizes access to the database's data from the primary region. If the default *survival goals* and *table localities* meet your needs, there is nothing else you need to do once you have set a database's primary region.

To add another database region, use the [`ALTER DATABASE ... ADD REGION` statement](/docs/stable/alter-database#add-region).

To show all of a database's regions, execute the [`SHOW REGIONS FROM DATABASE` statement](/docs/stable/show-regions).

> [!NOTE]
>
> If the default survival goals and table localities meet your needs, there is nothing else you need to do once you have set a database's primary region.

## Super regions

> [!NOTE]
>
> **This feature is in [preview](/docs/releases/cockroachdb-feature-availability.md)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).

Super regions allow you to define a set of [database regions](#database-regions) such that the following [schema objects](/docs/stable/schema-design-overview.md#database-schema-objects) will have all of their replicas stored *only* in regions that are members of the super region:

* [Regional tables](/docs/stable/table-localities.md#regional-tables) whose home region is a member of the super region.
* Any row of a [regional by row table](/docs/stable/table-localities.md#regional-by-row-tables) whose [home region](/docs/stable/alter-table.md#crdb_region) is a member of the super region.

The primary use case for super regions is data domiciling. As mentioned above, data from [regional](/docs/stable/table-localities.md#regional-tables) and [regional by row](/docs/stable/table-localities.md#regional-by-row-tables) tables will be stored only in regions that are members of the super region. Further, if the super region contains 3 or more regions and if you use [`REGION` survival goals](/docs/stable/multiregion-survival-goals#survive-region-failures), the data domiciled in the super region will remain available if you lose a region.

To use super regions, keep the following considerations in mind:

* Your cluster must be a [multi-region cluster](/docs/stable/multiregion-overview.md).
* Super regions [must be enabled](#enable-super-regions).
* Super regions can only contain one or more [database regions](/docs/stable/multiregion-overview.md#database-regions) that have already been added with [`ALTER DATABASE ... ADD REGION`](/docs/stable/alter-database#add-region).
* Each database region can only belong to one super region. In other words, given two super regions *A* and *B*, the set of database regions in *A* must be [disjoint](https://wikipedia.org/wiki/Disjoint_sets) from the set of database regions in *B*.
* You cannot [drop a region](/docs/stable/alter-database.md#drop-region) that is part of a super region until you either [alter the super region](/docs/stable/alter-database.md#alter-super-region) to remove it, or [drop the super region](/docs/stable/alter-database.md#drop-super-region) altogether.

For more information about how to enable and use super regions, see:

* [`ADD SUPER REGION`](/docs/stable/alter-database#add-super-region)
* [`DROP SUPER REGION`](/docs/stable/alter-database#drop-super-region)
* [`ALTER SUPER REGION`](/docs/stable/alter-database#alter-super-region)
* [`SHOW SUPER REGIONS`](/docs/stable/show-super-regions)

Note that super regions take a different approach to data domiciling than [`ALTER DATABASE ... PLACEMENT RESTRICTED`](/docs/stable/alter-database#placement). Specifically, super regions make it so that all [replicas](/docs/stable/architecture/overview.md#architecture-replica) (both voting and [non-voting](/docs/stable/architecture/replication-layer.md#non-voting-replicas)) are placed within the super region, whereas `PLACEMENT RESTRICTED` makes it so that there are no non-voting replicas.

For a demo on Super Regions, watch the following video:

[YouTube video player](https://www.youtube.com/embed/IXFTojYfA5A)

For more information about data domiciling using `PLACEMENT RESTRICTED`, see [Data Domiciling with CockroachDB](/docs/stable/data-domiciling.md).

If you want to do data domiciling for databases with [region survival goals](/docs/stable/multiregion-survival-goals.md#survive-region-failures)  using the higher-level multi-region abstractions, you must use super regions.  using the higher-level [multi-region abstractions](/docs/stable/multiregion-overview.md), you must use [super regions](/docs/stable/multiregion-overview.md#super-regions).  Using [`ALTER DATABASE ... PLACEMENT RESTRICTED`](/docs/stable/alter-database#placement) will not work for databases that are set up with region survival goals.

> [!NOTE]
>
> Super regions rely on the underlying [replication zone system](/docs/stable/configure-replication-zones.md), which was historically built for performance, not for domiciling. The replication system's top priority is to prevent the loss of data and it may override the zone configurations if necessary to ensure data durability. For more information, see [Replication Controls](/docs/stable/configure-replication-zones.md#types-of-constraints).

> [!NOTE]
>
> If you are using super regions in your cluster, there are additional constraints when using [secondary regions](#secondary-regions):

* If the [primary region](/docs/stable/alter-database.md#set-primary-region) is in a super region, the secondary region \*\*must\*\* be a region within the primary's super region.
* If the primary region is not in a super region, the secondary region \*\*must not\*\* be within a super region.

## Secondary regions

Secondary regions allow you to define a [database region](#database-regions) that will be used for failover in the event your [primary region](/docs/stable/alter-database.md#set-primary-region) goes down.  In other words, the secondary region will act as the primary region if the original primary region fails.

Secondary regions work as follows: when a secondary region is added to a database, a [lease preference](/docs/stable/configure-replication-zones.md) is added to the tables and indexes in that database to ensure that two [voting replicas](/docs/stable/configure-replication-zones.md) are moved into the secondary region.

This behavior is an improvement over versions of CockroachDB prior to v22.2.  In those versions, when the primary region failed, the [leaseholders](/docs/stable/architecture/replication-layer.md#leases) would be transferred to another [database region](#database-regions) at random, which could have negative effects on performance.

For more information about how to use secondary regions, see:

* [`SET SECONDARY REGION`](/docs/stable/alter-database#set-secondary-region)
* [`DROP SECONDARY REGION`](/docs/stable/alter-database#drop-secondary-region)

If you are using [super regions](#super-regions) in your cluster, there are additional constraints when using secondary regions:

* If the [primary region](/docs/stable/alter-database.md#set-primary-region) is in a super region, the secondary region \*\*must\*\* be a region within the primary's super region.
* If the primary region is not in a super region, the secondary region \*\*must not\*\* be within a super region.

[Secondary regions](/docs/stable/multiregion-overview.md#secondary-regions) are not compatible with databases containing [`REGIONAL BY ROW`](/docs/stable/table-localities#regional-by-row-tables) tables. CockroachDB does not prevent you from defining secondary regions on databases with regional by row tables, but the interaction of these features is not supported.

Therefore, Cockroach Labs recommends that you avoid defining secondary regions on databases that use regional by row table configurations.

## Survival goals

A *survival goal* dictates how many simultaneous failure(s) a database can survive. All tables within the same database operate with the **same survival goal**. Each database can have its own survival goal setting.

For more information, refer to [Multi-Region Survival Goals](/docs/stable/multiregion-survival-goals.md).

## Table localities

*Table locality* determines how CockroachDB optimizes access to the table's data. Every table in a multi-region database has a "table locality setting" that configures one or more *home regions* at the table or row level.

For more information, refer to [Table Localities](/docs/stable/table-localities.md).

## Additional features

The features listed in this section make working with multi-region clusters easier.

### Zone config extensions

Zone Config Extensions are a customization tool for advanced users to persistently modify the configuration generated by the standard [multi-region SQL abstractions](/docs/stable/multiregion-overview.md) on a per-region basis.

For more information, see [Zone Config Extensions](/docs/stable/zone-config-extensions.md).

## Schema changes in multi-region clusters

To reduce latency while making [online schema changes](/docs/stable/online-schema-changes.md), we recommend specifying a `lease_preference` [zone configuration](/docs/stable/configure-replication-zones.md) on the `system` database to a single region and running all subsequent schema changes from a node within that region. For example, if the majority of online schema changes come from machines that are geographically close to `us-east1`, run the following:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER DATABASE system CONFIGURE ZONE USING constraints = '{"+region=us-east1": 1}', lease_preferences = '[[+region=us-east1]]';
```

Run all subsequent schema changes from a node in the specified region.

If you do not intend to run more schema changes from that region, you can safely [remove the lease preference from the zone configuration](/docs/stable/alter-database.md#remove-a-replication-zone) for the system database.

## Next steps

* [How to Choose a Multi-Region Configuration](/docs/stable/choosing-a-multi-region-configuration.md)

## See also

* [When to Use `ZONE` vs. `REGION` Survival Goals](/docs/stable/multiregion-survival-goals#when-to-use-zone-vs-region-survival-goals)
* [When to Use `REGIONAL` vs. `GLOBAL` Tables](/docs/stable/table-localities#when-to-use-regional-vs-global-tables)
* [Global Tables](/docs/stable/global-tables.md)
* [Topology Patterns](/docs/stable/topology-patterns.md)
* [Disaster Recovery](/docs/stable/disaster-recovery-planning.md)
* [Develop and Deploy a Global Application](/docs/stable/movr.md#develop-and-deploy-a-global-application)
* [Low Latency Reads and Writes in a Multi-Region Cluster](/docs/stable/demo-low-latency-multi-region-deployment)
* [Migrate to Multi-Region SQL](/docs/stable/migrate-to-multiregion-sql)
* [`SET SECONDARY REGION`](/docs/stable/alter-database#set-secondary-region)
* [`ALTER DATABASE ... DROP SECONDARY REGION`](/docs/stable/alter-database#drop-secondary-region)
* [Zone Config Extensions](/docs/stable/zone-config-extensions.md)
* [Troubleshoot Replication Zones](/docs/stable/troubleshoot-replication-zones.md)