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.

Single-region

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

Deployment Type	Latency	Resiliency	Configuration
Development	Fast reads and writes	None	1 node No replication
Basic Production	Fast reads and writes	1 zone failure	1 region 3 zones 3+ nodes across zones

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 for each database.
• 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.

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

Pattern	Latency
Regional Tables	Low latency for single-region writes and multi-region stale reads.
Global Tables	Low-latency multi-region reads from all regions, at the expense of higher latency cross-region writes.
Follower Reads	Fast regional (historical) reads, slower cross-region writes.
Follow-the-Workload	Fast regional reads in the active region; slower cross-region reads elsewhere. Slower cross-region writes.

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 from a REGIONAL BY ROW 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 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:

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 behavior. In this case, latency will likely be unacceptably high.

See also

• Multi-Region Capabilities Overview
• How to Choose a Multi-Region Configuration
• When to Use ZONE vs. REGION Survival Goals
• When to Use REGIONAL vs. GLOBAL Tables
• Low Latency Reads and Writes in a Multi-Region Cluster
• Migrate to Multi-Region SQL
• Secondary regions
• ALTER DATABASE ... SET SECONDARY REGION
• ALTER DATABASE ... DROP SECONDARY REGION
• Topology Patterns Overview
  • Single-region patterns
    • Development
    • Basic Production
  • Multi-region patterns
    • REGIONAL Tables
    • GLOBAL Tables
    • Follower Reads
    • Follow-the-Workload