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

# Topology Patterns Overview

This page describes recommended topology patterns for running CockroachDB in a cloud environment and the expected impacts of these patterns on latency and resiliency.

> [!NOTE]
>
> You can observe latency for your cluster on the [Network Latency page](https://docs.cockroachlabs.com/docs/stable/ui-network-latency-page.md) of the DB Console.

## Single-region

When your clients are in a single geographic region, choosing a topology pattern is straightforward.

| Deployment Type | Latency | Resiliency | Configuration |
| - | - | - | - |
| Development | <ul><li>Fast reads and writes</li></ul> | <ul><li>None</li></ul> | <ul><li>1 node</li><li>No replication</li></ul> |
| [Basic Production](https://docs.cockroachlabs.com/docs/stable/topology-basic-production.md) | <ul><li>Fast reads and writes</li></ul> | <ul><li>1 zone failure</li></ul> | <ul><li>1 region</li><li>3 zones</li><li>3+ nodes across zones</li></ul> |

## Multi-region

When your clients are in multiple geographic regions, it is important to deploy your cluster across regions properly and then carefully choose the right:

* [Survival goal](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#survival-goals) for each database.
* [Table locality](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality) for each table.

Failure to consider either of these aspects can result in unexpected impacts on latency and resiliency. For more information, see the [Multi-Region Capabilities Overview](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality).

The multi-region patterns described in the following table are almost always table-specific. For example, you might use [Regional Tables](https://docs.cockroachlabs.com/docs/stable/regional-tables.md) for frequently updated tables that are tied to a specific region, and [Global Tables](https://docs.cockroachlabs.com/docs/stable/global-tables.md) for reference tables that are not tied to a specific region, and that are read frequently but updated infrequently.

| Pattern | Latency |
| - | - |
| [Regional Tables](https://docs.cockroachlabs.com/docs/stable/regional-tables.md) | Low latency for single-region writes and multi-region stale reads. |
| [Global Tables](https://docs.cockroachlabs.com/docs/stable/global-tables.md) | Low-latency multi-region reads from all regions, at the expense of higher latency cross-region writes. |
| [Follower Reads](https://docs.cockroachlabs.com/docs/stable/topology-follower-reads.md) | Fast regional (historical) reads, slower cross-region writes. |
| [Follow-the-Workload](https://docs.cockroachlabs.com/docs/stable/topology-follow-the-workload.md) | Fast regional reads in the active region; slower cross-region reads elsewhere. Slower cross-region writes. |

> [!NOTE]
>
> In [multi-region databases](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#table-locality), the resiliency of each database depends on its [survival goal settings](https://docs.cockroachlabs.com/docs/stable/multiregion-overview.md#survival-goals).

If you want low-latency read-only access to your data in multiple regions, Cockroach Labs recommends that you default to using stale follower reads on `REGIONAL` tables (the default locality). However, there are two reasons you might want to upgrade a table to `GLOBAL`:

* You want low-latency consistent (non-stale) read access to the table in multiple regions from read-write transactions. One case where this is important is if the table is referenced by a [foreign key](https://docs.cockroachlabs.com/docs/stable/foreign-key.md) from a [`REGIONAL BY ROW`](https://docs.cockroachlabs.com/docs/stable/regional-tables#regional-by-row-tables) table. In these cases, the foreign key check that accompanies a write cannot use a stale read because it must be transactionally consistent with the write. To keep this foreign key check fast, you can make the reference table `GLOBAL`, at the expense of slower writes to that table.
* When an [ORM](https://docs.cockroachlabs.com/docs/stable/install-client-drivers.md) or application-level tool makes follower reads too hard to use. In these cases, `GLOBAL` tables can allow you to achieve low-latency reads through a schema-level setting.

In summary, Cockroach Labs recommends that you use follower reads whenever you can, and use `GLOBAL` tables when you can't.

In the following demo, we show the importance of choosing the correct topology patterns for your tables:

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

## Anti-patterns

The following anti-patterns are ineffective or risky:

* Single-region deployments using 2 zones, or multi-region deployments using 2 regions. In these cases, the cluster would be unable to survive the loss of a single zone or a single region, respectively.
* Broadly distributed multi-region deployments (e.g., `us-west`, `asia`, and `europe`) using only the default [Follow-the-Workload](https://docs.cockroachlabs.com/docs/stable/topology-follow-the-workload.md) behavior. In this case, latency will likely be unacceptably high.

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