Skip to content

Commit

Permalink
Break out smaller topics from multiregion overview
Browse files Browse the repository at this point in the history 
... with the goal of increasing ease of understanding and findability
from searches.

Summary of changes:

- Break out 'Choosing a multi-region configuration' from the bottom of
  the original overview page; also, add a "locality vs. survival"
  feature matrix-y table to make it easier (?) to understand

- Add a "When to use ZONE vs REGION" page for easier searching etc.

- Add a "When to use REGIONAL vs GLOBAL" page, also for easier searching
  etc.

Addresses #8958, #9708, #9709, #9884, #9886.
  • Loading branch information
@rmloveland
rmloveland committed Mar 2, 2021
1 parent 64d938b commit 95d931c
Show file tree
Hide file tree
Showing 5 changed files with 132 additions and 14 deletions.
18 changes: 18 additions & 0 deletions _includes/sidebar-data-v21.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -621,6 +621,24 @@
"urls": [
"/${VERSION}/multiregion-overview.html"
]
},
{
"title": "Choosing a multi-region configuration",
"urls": [
"/${VERSION}/multiregion-overview.html"
]
},
{
"title": "When to use ZONE vs. REGION Survival Goals",
"urls": [
"/${VERSION}/when-to-use-zone-vs-region-survival-goals.html"
]
},
{
"title": "When to use REGIONAL vs. GLOBAL tables",
"urls": [
"/${VERSION}/when-to-use-regional-vs-global-tables.html"
]
}
]
},
Expand Down
43 changes: 43 additions & 0 deletions v21.1/choosing-a-multi-region-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Choosing a multi-region configuration
summary: Learn how to use CockroachDB's improved multi-region user experience.
toc: true
---

This page has high-level information about how to configure a [multi-region cluster's](multiregion-overview.html) [survival goals](multiregion-overview.html#survival-goals) and [table locality](multiregion-overview.html#table-locality).

The options for configuring your multi-region cluster include:

- _Change nothing_: Using the [default settings](multiregion-overview.html#default-settings), you get zone survival, low-latency single-region writes, and multi-region stale reads.

- _Change only [survival goals](multiregion-overview.html#survival-goals)_: In this configuration, you move from availability zone (AZ) to get region survival, single-region writes, and multi-region stale reads. This configuration is useful for single-region apps that need higher levels of survival.

- _Change only [table locality](multiregion-overview.html#table-locality)_: In this configuration, you accept the default zone survival, and optimize for low-latency multi-region reads and writes. This is useful for multi-region apps that require different read/write latency guarantees for different tables in the database, and are not concerned with surviving a region failure.

- _Change both [survival goals](multiregion-overview.html#survival-goals) and [table locality](multiregion-overview.html#table-locality)_: In this configuration, you upgrade from zone to region survival, and optimize for low-latency multi-region reads. Multi-region writes are higher-latency because they have to move across the network. This is useful for multi-region apps that want a high level of survival.

The table below offers another view of how the configuration options described above map to:

- The performance characteristics of specific survival goal/table locality combinations.
- The types of applications that can benefit from each combination.

| locality ↓ survival → | `ZONE` | `REGION` |
|-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `REGIONAL BY TABLE` | Low-latency for single-region writes and multi-region stale reads. | Single-region writes are higher latency than for ZONE, as at least one additional region must be consulted for each write. Stale multi-region reads are of comparable latency to ZONE survival. |
| | For single-region apps that can accept risk of region failure. | For single-region apps that must survive region failure. |
| `REGIONAL BY ROW` | Low-latency consistent multi-region reads & writes for rows which are homed in specific regions. | Low-latency consistent multi-region reads. Low-latency single-region writes with the right settings. |
| | For multi-region apps which read/write individual rows of the table from a specific region, and can accept the risk of region failure. | Same as for ZONE survival, but for apps that must survive a region failure. |
| `GLOBAL` | Low-latency multi-region reads. Writes are higher latency than reads. | Low-latency multi-region reads. Writes are higher latency than reads due to cross-region replication. |
| | For multi-region apps that need low-latency reads of a "read-mostly" table. | For multi-region apps that need low-latency reads of a "read-mostly" table, and the ability to survive region failures. |

{{site.data.alerts.callout_info}}
Different databases and tables within the same cluster can each use different combinations of the settings above.
{{site.data.alerts.end}}

## See also

- [Multi-region overview](multiregion-overview.html)
- [When to use `REGIONAL` vs. `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)
- [When to use `ZONE` vs. `REGION` survival goals](when-to-use-zone-vs-region-survival-goals.html)
- [Topology Patterns](topology-patterns.html)
- [Disaster Recovery](disaster-recovery.html)
18 changes: 4 additions & 14 deletions v21.1/multiregion-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -231,23 +231,13 @@ To optimize read access to the data in a table from any region (that is, globall
ALTER TABLE <table> SET LOCALITY GLOBAL;
~~~

## Choosing a multi-region configuration
## Next steps

In this section we will try to explain how to change [the default settings](#default-settings) of your multi-region cluster to meet your application's needs.

The options for changing your multi-region cluster's configuration include:

- _Change nothing_: Using the [default settings](#default-settings), you get zone survival, low-latency single-region writes, and multi-region stale reads.

- _Change only [survival](#survival-goals)_: In this configuration, you upgrade from availability zone (AZ) to get region survival, single-region writes, and multi-region stale reads. This configuration is useful for single-region apps that need higher levels of survival.

- _Change only [table locality](#table-locality)_: In this configuration, you accept the default zone survival, and optimize for low-latency multi-region reads and writes. This is useful for multi-region apps that want low-latency writes and are not concerned with surviving a region failure.

- _Change both [survival](#survival-goals) and [table locality](#table-locality)_: In this configuration, you upgrade from zone to region survival, and optimize for low-latency multi-region reads. Single-region writes can be made low-latency with the right settings, but multi-region writes are higher-latency because they have to move across the network. This is useful for multi-region apps that want a high level of survival.

Finally, note that different databases within the same cluster can each use different combinations of the settings above.
+ [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html)

## See also

- [When to use `REGIONAL` vs. `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)
- [When to use `ZONE` vs. `REGION` survival goals](when-to-use-zone-vs-region-survival-goals.html)
- [Topology Patterns](topology-patterns.html)
- [Disaster Recovery](disaster-recovery.html)
34 changes: 34 additions & 0 deletions v21.1/when-to-use-regional-vs-global-tables.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: When to use REGIONAL vs. GLOBAL tables
summary: Learn how to use CockroachDB's improved multi-region user experience.
toc: true
---

<span class="version-tag">New in v21.1:</span> [_Table Localities_](multiregion-overview.html#table-locality) tell CockroachDB how to optimize access to a table's data in a multi-region cluster. CockroachDB uses the table locality setting to determine how to optimize access to the table's data from that locality.

The following table localities are available:

- `REGIONAL`
- `GLOBAL`

Use [`REGIONAL` tables](multiregion-overview.html#regional-by-row-tables) if:

- Your application requires low-latency reads and writes from a single region (either at the [row level](multiregion-overview.html#regional-by-row-tables) or the [table level](multiregion-overview.html#regional-tables)).
- Access to the table's data can be slower (higher latency) from other regions.

Use [`GLOBAL` tables](multiregion-overview.html#global-tables) if:

- Your application has a "read-mostly" table of reference data that is rarely updated, and that needs to be available to all regions.
- You can accept that writes to the table will incur higher latencies from any given region, since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future" (documentation forthcoming).

{{site.data.alerts.callout_success}}
For more information about how to choose an overall multi-region configuration, see [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html).
{{site.data.alerts.end}}

## See also

- [Multi-region Overview](multiregion-overview.html)
- [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html)
- [When to use `ZONE` vs. `REGION` survival goals](when-to-use-zone-vs-region-survival-goals.html)
- [Topology Patterns](topology-patterns.html)
- [Disaster Recovery](disaster-recovery.html)
33 changes: 33 additions & 0 deletions v21.1/when-to-use-zone-vs-region-survival-goals.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: When to use ZONE vs. REGION survival goals
summary: Learn how to use CockroachDB's improved multi-region user experience.
toc: true
---

<span class="version-tag">New in v21.1:</span> [_Survival Goals_](multiregion-overview.html#survival-goals) dictate how many simultaneous failure(s) a [multi-region database](multiregion-overview.html) can survive. All tables within the same database operate with the same survival goal. Each database is allowed to have its own survival goal setting.

Allowed survival goals include:

- `ZONE` (default)
- `REGION`

Set a [`ZONE` survival goal](multiregion-overview.html#surviving-zone-failures) if:

- You can accept that if multiple zones fail in the same region, the database may be unavailable.

Set a [`REGION` survival goal](multiregion-overview.html#surviving-region-failures) if:

- The database must remain available, even if a region goes down.
- You can accept the performance cost: write latency will be increased by at least as much as the round-trip time to the nearest region. Read performance will be unaffected.

{{site.data.alerts.callout_success}}
For more information about how to choose a multi-region configuration, see [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html).
{{site.data.alerts.end}}

## See also

+ [Multi-region overview](multiregion-overview.html)
+ [Choosing a multi-region configuration](choosing-a-multi-region-configuration.html)
+ [When to use `REGIONAL` vs `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)
- [Topology Patterns](topology-patterns.html)
- [Disaster Recovery](disaster-recovery.html)

0 comments on commit 95d931c

Please sign in to comment.