diff --git a/_includes/sidebar-data-v21.1.json b/_includes/sidebar-data-v21.1.json index 7ec7b3a377f..7244d954d79 100644 --- a/_includes/sidebar-data-v21.1.json +++ b/_includes/sidebar-data-v21.1.json @@ -621,6 +621,24 @@ "urls": [ "/${VERSION}/multiregion-overview.html" ] + }, + { + "title": "Choosing a multi-region configuration", + "urls": [ + "/${VERSION}/choosing-a-multi-region-configuration.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" + ] } ] }, diff --git a/v21.1/choosing-a-multi-region-configuration.md b/v21.1/choosing-a-multi-region-configuration.md new file mode 100644 index 00000000000..6d311d3ffc1 --- /dev/null +++ b/v21.1/choosing-a-multi-region-configuration.md @@ -0,0 +1,55 @@ +--- +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 (the default). + - Low-latency reads and writes from a single region. + - Low-latency stale reads from all other regions. + +- _Change only [survival goals](multiregion-overview.html#survival-goals)_: This configuration is useful for single-region apps that need higher levels of survival. In this configuration, you move from availability zone (AZ) survival to get: + - Region survival. + - Low-latency reads from a single region. + - Low-latency stale reads from all other regions. + - Higher-latency writes from all regions (due to region survival). + +- _Change only [table locality](multiregion-overview.html#table-locality)_: 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. In this configuration, you get: + - Zone survival (the default). + - Low-latency reads and writes from all regions. + +- _Change both [survival goals](multiregion-overview.html#survival-goals) and [table locality](multiregion-overview.html#table-locality)_: This is useful for multi-region apps that want a high level of survival. In this configuration, you move from zone survival and get: + - Region survival. + - Low-latency reads from all regions. + - Higher-latency writes from all regions (due to region 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 if you are writing to a row from its home region. | +| | 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. There should be minimal difference in write latencies between ZONE and REGION survival due to a new custom non-blocking transaction protocol. | +| | 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) diff --git a/v21.1/multiregion-overview.md b/v21.1/multiregion-overview.md index fb0446d7429..883c7482fbd 100644 --- a/v21.1/multiregion-overview.md +++ b/v21.1/multiregion-overview.md @@ -231,23 +231,13 @@ To optimize read access to the data in a table from any region (that is, globall ALTER 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 `ZONE` vs. `REGION` survival goals](when-to-use-zone-vs-region-survival-goals.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) diff --git a/v21.1/when-to-use-regional-vs-global-tables.md b/v21.1/when-to-use-regional-vs-global-tables.md new file mode 100644 index 00000000000..4f675812a5b --- /dev/null +++ b/v21.1/when-to-use-regional-vs-global-tables.md @@ -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 +--- + +New in v21.1: [_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) diff --git a/v21.1/when-to-use-zone-vs-region-survival-goals.md b/v21.1/when-to-use-zone-vs-region-survival-goals.md new file mode 100644 index 00000000000..869d7460c8d --- /dev/null +++ b/v21.1/when-to-use-zone-vs-region-survival-goals.md @@ -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 +--- + +New in v21.1: [_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 a single node failure up to an entire zone failure. If multiple zones fail in the same region, the database may become 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)