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

# Topology Patterns Overview

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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 <InternalLink path="ui-network-latency-page">Network Latency page</InternalLink> of the DB Console.
</Note>

## 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>                          |
| <InternalLink path="topology-basic-production">Basic Production</InternalLink> | <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:

* <InternalLink path="multiregion-overview#survival-goals">Survival goal</InternalLink> for each database.
* <InternalLink path="multiregion-overview">Table locality</InternalLink> for each table.

Failure to consider either of these aspects can result in unexpected impacts on latency and resiliency. For more information, see the <InternalLink path="multiregion-overview">Multi-Region Capabilities Overview</InternalLink>.

The multi-region patterns described in the following table are almost always table-specific. For example, you might use <InternalLink path="regional-tables">Regional Tables</InternalLink> for frequently updated tables that are tied to a specific region, and <InternalLink path="global-tables">Global Tables</InternalLink> for reference tables that are not tied to a specific region, and that are read frequently but updated infrequently.

| Pattern                                                                              | Latency                                                                                                    |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| <InternalLink path="regional-tables">Regional Tables</InternalLink>                  | Low latency for single-region writes and multi-region stale reads.                                         |
| <InternalLink path="global-tables">Global Tables</InternalLink>                      | Low-latency multi-region reads from all regions, at the expense of higher latency cross-region writes.     |
| <InternalLink path="topology-follower-reads">Follower Reads</InternalLink>           | Fast regional (historical) reads, slower cross-region writes.                                              |
| <InternalLink path="topology-follow-the-workload">Follow-the-Workload</InternalLink> | Fast regional reads in the active region; slower cross-region reads elsewhere. Slower cross-region writes. |

<Note>
  In <InternalLink path="multiregion-overview">multi-region databases</InternalLink>, the resiliency of each database depends on its <InternalLink path="multiregion-overview#survival-goals">survival goal settings</InternalLink>.
</Note>

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 <InternalLink path="foreign-key">foreign key</InternalLink> from a <InternalLink path="regional-tables#regional-by-row-tables">`REGIONAL BY ROW`</InternalLink> 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 <InternalLink path="install-client-drivers">ORM</InternalLink> 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:

<iframe width="560" height="315" src="https://www.youtube.com/embed/sO1Mr0Gmde0" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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 <InternalLink path="topology-follow-the-workload">Follow-the-Workload</InternalLink> behavior. In this case, latency will likely be unacceptably high.

## See also

* <InternalLink path="multiregion-overview">Multi-Region Capabilities Overview</InternalLink>
* <InternalLink path="choosing-a-multi-region-configuration">How to Choose a Multi-Region Configuration</InternalLink>
* <InternalLink path="multiregion-survival-goals#when-to-use-zone-vs-region-survival-goals">When to Use `ZONE` vs. `REGION` Survival Goals</InternalLink>
* <InternalLink path="table-localities#when-to-use-regional-vs-global-tables">When to Use `REGIONAL` vs. `GLOBAL` Tables</InternalLink>
* <InternalLink path="multiregion-overview#secondary-regions">Secondary regions</InternalLink>
* <InternalLink path="alter-database#set-secondary-region">`ALTER DATABASE ... SET SECONDARY REGION`</InternalLink>
* <InternalLink path="alter-database#drop-secondary-region">`ALTER DATABASE ... DROP SECONDARY REGION`</InternalLink>
* <InternalLink path="topology-patterns">Topology Patterns Overview</InternalLink>
  * Single-region patterns
    * <InternalLink path="topology-basic-production">Basic Production</InternalLink>
  * Multi-region patterns
    * <InternalLink path="regional-tables">`REGIONAL` Tables</InternalLink>
    * <InternalLink path="global-tables">`GLOBAL` Tables</InternalLink>
    * <InternalLink path="topology-follower-reads">Follower Reads</InternalLink>
    * <InternalLink path="topology-follow-the-workload">Follow-the-Workload</InternalLink>
