Merge pull request #9900 from cockroachdb/20210226-multiregion-when-do-i

Break out smaller topics from multiregion overview

_includes/sidebar-data-v21.1.json

@@ -627,6 +627,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"
+                ]
               }
             ]
           },

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.
+
+| <div style="width: 200px;"></div> locality &#8595; survival &#8594; | `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)

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

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: false
+---
+
+<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)

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: false
+---
+
+<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 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)