Break out smaller topics from multiregion overview

[rmloveland]

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

[cockroach-teamcity]

This change is 

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/e3863d96335ee8b62ad75d30ca8f4aef6dc892f4/

Edited pages:

• v21.1/choosing-a-multi-region-configuration.md
• v21.1/multiregion-overview.md
• v21.1/when-to-use-regional-vs-global-tables.md
• v21.1/when-to-use-zone-vs-region-survival-goals.md

[rmloveland]

Adam & Nathan: FYI this is kind of a "intermediate step" PR with the goal of breaking some stuff out of the giant overview page so we have bones to hang stuff on as I have started writing SQL reference pages so I have something to link to from upcoming tutorials. The PR summary has the details - It's a combo of edits and a couple new pages for people who are just trying to find "when to choose A vs. B".

Would appreciate any feedback - esp. if the advice is wrong or needs clarifying! Thanks!

[ajstorm]

Nice to see the documentation take form.

Reviewed 5 of 5 files at r1.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @nvanbenschoten and @rmloveland)

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r1 (raw file):

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 changing your multi-region cluster's configuration include:

This section is great. I wonder though if it might be better to frame this more from the user's perspective instead of from the system perspective. For example, we could rewrite the above, and the first bullet point below as:

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

If your application predominantly reads/writes from a single region, requires fast stale reads from the other regions, and must only tolerate zone failures, the default configuration is sufficient."

Then subsequent bullets would start with the customer use-case, and finish with what needs changing. For someone new to the system, it might be a more natural way of consuming the information.

---

v21.1/choosing-a-multi-region-configuration.md, line 13 at r1 (raw file):

- _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 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.

I think we should avoid the work "upgrade" here, as the survivability gets better, but the latency will get worse. Some more neutral words might be "move", "switch", "convert", "transition".

---

v21.1/choosing-a-multi-region-configuration.md, line 15 at r1 (raw file):

- _Change only [survival goals](multiregion-overview.html#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](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 want low-latency writes and are not concerned with surviving a region failure.

I worry that this last line could be a bit misleading. For example, GLOBAL tabled don't guarantee low-latency writes, so we could be setting the wrong expectations here. What about something more neutral, like "This is useful for multi-region application that require different read/write latency guarantees for different tables in the database (see below for details)"?

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r1 (raw file):

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 might be confusing without additional context. We might want to defer this detail to the table below.

---

v21.1/choosing-a-multi-region-configuration.md, line 26 at r1 (raw file):

| locality ↓ survival → | `ZONE`                                                                                 | `REGION`                                                                                            |
|-----------------------------------+----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------|
| `REGIONAL BY TABLE`               | Low-latency single-region writes, multi-region stale reads.                            | Single-region writes, multi-region stale reads.                                                     |

Nit: The comma here is throwing me off. I think what we mean on the ZONE side is "Low-latency for single region writes and multi-region stale reads". On the REGION side, how about "Single region writes are higher latency than with ZONE survival, as at least one additional region must be consulted for each write. Stale reads are of comparable latency to ZONE survival."

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

| `REGIONAL BY TABLE`               | Low-latency single-region writes, multi-region stale reads.                            | Single-region writes, multi-region stale reads.                                                     |
|                                   | 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 multi-region reads & writes.                                               | Low-latency multi-region reads. Low-latency single-region writes with the right settings.           |

I think the first column here could do with some clarification, because as it reads, it sounds like the best option (low latency for both reads and writes). We should add here that the latency guarantees are only for rows which live in the targeted region, and only if the read/write access is also within that region. For the right column, can we be more specific about what we mean by "with the right settings"?

---

v21.1/choosing-a-multi-region-configuration.md, line 29 at r1 (raw file):

For multi-region apps that need low-latency writes, can accept risk of region failure.

I think we need something more nuanced here. Something like "For multi-region applications which read/write individual rows of the table from a specific region" and we might want to provide an example. Similarly, here:

For multi-region apps that want a high level of survival.

We should probably say something like "Same requirements, but requires the ability to survive a region failure."

---

v21.1/choosing-a-multi-region-configuration.md, line 30 at r1 (raw file):

| `REGIONAL BY ROW`                 | Low-latency multi-region reads & writes.                                               | Low-latency multi-region reads. Low-latency single-region writes with the right settings.           |
|                                   | For multi-region apps that need low-latency writes, can accept risk of region failure. | For multi-region apps that want a high level of survival.                                           |
| `GLOBAL`                          | Low-latency multi-region reads. High-latency writes.                                   | Low-latency multi-region reads.  High-latency writes due to cross-region replication.               |

Nit: We might want to reword "High-latency writes", as they sound pretty scary. Maybe we can say something like "writes are higher latency as they're prioritized lower than reads" (not even sure about this, but maybe @nvanbenschoten has a good thought here). Also, do we think we need to call out the "cross-region replication"? Won't this be a smaller impact to latency than writing into the future?

---

v21.1/choosing-a-multi-region-configuration.md, line 31 at r1 (raw file):

high level of survival.

Nit: "...and the ability to survive region failures"?

---

v21.1/choosing-a-multi-region-configuration.md, line 34 at r1 (raw file):

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

database and tables?

---

v21.1/when-to-use-regional-vs-global-tables.md, line 7 at r1 (raw file):

---

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

Nit: Space before "tell".

---

v21.1/when-to-use-regional-vs-global-tables.md, line 16 at r1 (raw file):

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

- Your application requires low-latency reads and writes from a single region.

Nit: Might benefit from adding (either at a table level, or for individual rows of a table) at the end of this line.

---

v21.1/when-to-use-regional-vs-global-tables.md, line 23 at r1 (raw file):

- 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 have to be replicated across every region to make the global low-latency reads possible.

Nit: I think this is a good way of thinking about things from a customer perspective, but it's not 100% technically accurate. For example, if you're in ZONE survivability, and you're writing to the PRIMARY region, the higher latency isn't caused by replication, but rather, is a result of the fact that we're writing into the future. I know that this is far more nuance than we want customers to consume, but I worry that the wording as-is will cause confusion for super-users.

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 17 at r1 (raw file):

- You can accept that if multiple zones fail in the same region, the database may be unavailable.
- You need better performance: low-latency single-region writes, and multi-region stale reads.

Nit: The "low-latency single-region writes" part has some caveats (i.e. it only applies to REGIONAL tables, and even then, only in specific regions). Wondering if we want to drop it from here.

[rmloveland]

Thanks for the review Adam! I think almost every item of feedback is addressed, I just had 1-2 questions below. PTAL

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @ajstorm and @nvanbenschoten)

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

This section is great. I wonder though if it might be better to frame this more from the user's perspective instead of from the system perspective. For example, we could rewrite the above, and the first bullet point below as:

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

If your application predominantly reads/writes from a single region, requires fast stale reads from the other regions, and must only tolerate zone failures, the default configuration is sufficient."

Then subsequent bullets would start with the customer use-case, and finish with what needs changing. For someone new to the system, it might be a more natural way of consuming the information.

Changed the intro to say "The options for configuring your multi-region cluster include:"

Re: changing the sub-topics, I would prefer not to rewrite them for now since they are copied from something we already merged - or should I say I'd rather not rewrite them ... yet. I need to get more stuff up on the site and cross-link it around. As we get closer to the release and more things are filled in, I will do a review of everything and revise based on the (hopefully) better, simpler understandings/explanations we have at that time. Right now I want to work a bit more breadth-first. But I totes agree they can/will be made better. Hope that's not too annoying!

---

v21.1/choosing-a-multi-region-configuration.md, line 13 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

I think we should avoid the work "upgrade" here, as the survivability gets better, but the latency will get worse. Some more neutral words might be "move", "switch", "convert", "transition".

Good idea - went with "move"

---

v21.1/choosing-a-multi-region-configuration.md, line 15 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

I worry that this last line could be a bit misleading. For example, GLOBAL tabled don't guarantee low-latency writes, so we could be setting the wrong expectations here. What about something more neutral, like "This is useful for multi-region application that require different read/write latency guarantees for different tables in the database (see below for details)"?

Updated to that language!

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

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 might be confusing without additional context. We might want to defer this detail to the table below.

I agree - I'd rather leave it for now since these are alpha docs anyway, and this is language we already merged in another PR. As more stuff gets written I will have more context to link to, and more ways of saying stuff. And as above I def agree we should do what you are saying! Will end up revising this again as we get later into cycle.

---

v21.1/choosing-a-multi-region-configuration.md, line 26 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: The comma here is throwing me off. I think what we mean on the ZONE side is "Low-latency for single region writes and multi-region stale reads". On the REGION side, how about "Single region writes are higher latency than with ZONE survival, as at least one additional region must be consulted for each write. Stale reads are of comparable latency to ZONE survival."

Updated to use that language, thanks!

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

I think the first column here could do with some clarification, because as it reads, it sounds like the best option (low latency for both reads and writes). We should add here that the latency guarantees are only for rows which live in the targeted region, and only if the read/write access is also within that region. For the right column, can we be more specific about what we mean by "with the right settings"?

Hmm I actually do not know what "the right settings" are, this is something Nathan typed in a comment somewhere. Do you know what they are? Sorry, guess I should have asked this already. Is the answer "RBR + when you are writing to a row whose home region is also the DB's primary region"?

---

v21.1/choosing-a-multi-region-configuration.md, line 29 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

For multi-region apps that need low-latency writes, can accept risk of region failure.

I think we need something more nuanced here. Something like "For multi-region applications which read/write individual rows of the table from a specific region" and we might want to provide an example. Similarly, here:

For multi-region apps that want a high level of survival.

We should probably say something like "Same requirements, but requires the ability to survive a region failure."

Updated to use approx that language!

---

v21.1/choosing-a-multi-region-configuration.md, line 30 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: We might want to reword "High-latency writes", as they sound pretty scary. Maybe we can say something like "writes are higher latency as they're prioritized lower than reads" (not even sure about this, but maybe @nvanbenschoten has a good thought here). Also, do we think we need to call out the "cross-region replication"? Won't this be a smaller impact to latency than writing into the future?

How about "writes are higher latency than reads" without mentioning prioritization (yet), since we don't have docs on non-blocking transactions yet? (I have read the RFC but only once so far so not 100% familiar)

Re: cross-region replication, IDK - I am happy to use different language. I guess psychologically we need to give the reader something that is "different" in the REGION survival column that may explain any write latency differences (if any?).

If there is no difference in write latency between ZONE and REGION we could say something like "there should be minimal difference in write latencies between ZONE and REGION survival due to a new custom non-blocking transaction protocol" or similar and leave it at that, and come back and link arch docs once written

Nathan, what do you think?

---

v21.1/choosing-a-multi-region-configuration.md, line 31 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

high level of survival.

Nit: "...and the ability to survive region failures"?

Updated!

---

v21.1/choosing-a-multi-region-configuration.md, line 34 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

database and tables?

Yes! Updated to say "different DBs and tables"

---

v21.1/when-to-use-regional-vs-global-tables.md, line 7 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: Space before "tell".

Fixed!

---

v21.1/when-to-use-regional-vs-global-tables.md, line 16 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: Might benefit from adding (either at a table level, or for individual rows of a table) at the end of this line.

Added!

FYI also removed bullet 3 about "controlling where data is located" since I understand from some comments by Nathan elsewhere that this is Not A Thing (tm) - everything is everywhere. Still drilling this into my brain

---

v21.1/when-to-use-regional-vs-global-tables.md, line 23 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: I think this is a good way of thinking about things from a customer perspective, but it's not 100% technically accurate. For example, if you're in ZONE survivability, and you're writing to the PRIMARY region, the higher latency isn't caused by replication, but rather, is a result of the fact that we're writing into the future. I know that this is far more nuance than we want customers to consume, but I worry that the wording as-is will cause confusion for super-users.

Agreed! As discussed in another comment we should have docs for non-blocking transactions later in the cycle. What do you think about:

" ... since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future" (documentation forthcoming)."

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 17 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

Nit: The "low-latency single-region writes" part has some caveats (i.e. it only applies to REGIONAL tables, and even then, only in specific regions). Wondering if we want to drop it from here.

Dropped it - can let the description of the higher latency cost for SURVIVE REGION below do the talking

[rmloveland]

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @ajstorm and @nvanbenschoten)

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

I agree - I'd rather leave it for now since these are alpha docs anyway, and this is language we already merged in another PR. As more stuff gets written I will have more context to link to, and more ways of saying stuff. And as above I def agree we should do what you are saying! Will end up revising this again as we get later into cycle.

actually belay that - we discuss what the "right settings" are below in a different comment. will update this based on that and/or defer as you suggest once we figure that out

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/95d931c761077ae78f4253d46517859a3ef97135/

Edited pages:

• v21.1/choosing-a-multi-region-configuration.md
• v21.1/multiregion-overview.md
• v21.1/when-to-use-regional-vs-global-tables.md
• v21.1/when-to-use-zone-vs-region-survival-goals.md

[ajstorm]

Reviewed 3 of 3 files at r2.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @nvanbenschoten)

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Changed the intro to say "The options for configuring your multi-region cluster include:"

Re: changing the sub-topics, I would prefer not to rewrite them for now since they are copied from something we already merged - or should I say I'd rather not rewrite them ... yet. I need to get more stuff up on the site and cross-link it around. As we get closer to the release and more things are filled in, I will do a review of everything and revise based on the (hopefully) better, simpler understandings/explanations we have at that time. Right now I want to work a bit more breadth-first. But I totes agree they can/will be made better. Hope that's not too annoying!

SGTM

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Hmm I actually do not know what "the right settings" are, this is something Nathan typed in a comment somewhere. Do you know what they are? Sorry, guess I should have asked this already. Is the answer "RBR + when you are writing to a row whose home region is also the DB's primary region"?

@nvanbenschoten for "right settings" are we referring to the optimizations that Becca put in? Something else?

---

v21.1/when-to-use-regional-vs-global-tables.md, line 23 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Agreed! As discussed in another comment we should have docs for non-blocking transactions later in the cycle. What do you think about:

" ... since writes use a novel non-blocking transaction protocol that uses a timestamp "in the future" (documentation forthcoming)."

Works for me.

[nvanbenschoten]

Looking good!

Reviewed 2 of 5 files at r1, 1 of 3 files at r2.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @ajstorm and @rmloveland)

---

_includes/sidebar-data-v21.1.json, line 628 at r2 (raw file):

                "title": "Choosing a multi-region configuration",
                "urls": [
                  "/${VERSION}/multiregion-overview.html"

This link is still going to the overview. Took me a few clicks to realize.

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Is the answer "RBR + when you are writing to a row whose home region is also the DB's primary region"?

I think this is what I meant, and it relates to Adam's initial comment on this thread.

---

v21.1/choosing-a-multi-region-configuration.md, line 30 at r1 (raw file):
Even just "higher-latency instead of "high-latency" SGTM.

If there is no difference in write latency between ZONE and REGION we could say something like "there should be minimal difference in write latencies between ZONE and REGION survival due to a new custom non-blocking transaction protocol" or similar and leave it at that, and come back and link arch docs once written

👍

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r2 (raw file):

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:

nit: the spacing seems a little compressed between this line and the next. Not sure if there's anything to do.

---

v21.1/choosing-a-multi-region-configuration.md, line 11 at r2 (raw file):

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.

"single-region reads and write"

Same thing in the next option.

---

v21.1/choosing-a-multi-region-configuration.md, line 11 at r2 (raw file):

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.

The "low-latency/high-latency" vs. "single-region/multi-region" distinctions are subtle. I wonder if there's anything better we could say here to distinguish them. Should we be using "from a single region"/"from all regions" to drive home the idea that we're talking about access performance? So something like:

you get zone survival, low-latency reads and writes from a single region, and low-latency stale reads from all other regions

you get region survival, low-latency reads from a single region, higher-latency writes from a single region, and low-latency stale reads from all other regions

... low-latency reads and writes from all regions

... low-latency reads from all regions and higher-latency writes from all regions

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

- _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.

Should we use "move" instead of "upgrade" here as well?

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

- _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.

It's confusing that we mention writes being slower in this option, but not in the "Change only survival goals" option.

We should either hint that writes are slower (independent of locality) for REGION survivability across this overview, or ignore it.

---

v21.1/choosing-a-multi-region-configuration.md, line 24 at r2 (raw file):

- The types of applications that can benefit from each combination.

| locality ↓ survival → | `ZONE`                                                                                                                                 | `REGION`                                                                                                                                                                                         |

nit: the first column is getting compressed

---

v21.1/multiregion-overview.md, line 240 at r2 (raw file):

## See also

- [When to use `REGIONAL` vs. `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)

Should we reverse this order? We talk about ZONE vs. REGION before REGIONAL vs. GLOBAL everywhere else.

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 16 at r2 (raw file):

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.

It would be worth mentioning what we can survive with this setting - a single node failure up to an entire zone failure.

[rmloveland]

Thanks Nathan! I think I fixed all the things. PTAL!

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @ajstorm and @nvanbenschoten)

---

_includes/sidebar-data-v21.1.json, line 628 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

This link is still going to the overview. Took me a few clicks to realize.

Ah! Fixed

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r1 (raw file):

Previously, ajstorm (Adam Storm) wrote…

SGTM

(FYI ended up changing subtopics mostly as you requested - see below)

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

Is the answer "RBR + when you are writing to a row whose home region is also the DB's primary region"?

I think this is what I meant, and it relates to Adam's initial comment on this thread.

Updated to say just that! (RBR + when you are writing to row whose home is also primary)

---

v21.1/choosing-a-multi-region-configuration.md, line 30 at r1 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

Even just "higher-latency instead of "high-latency" SGTM.

If there is no difference in write latency between ZONE and REGION we could say something like "there should be minimal difference in write latencies between ZONE and REGION survival due to a new custom non-blocking transaction protocol" or similar and leave it at that, and come back and link arch docs once written

👍

Cool - left at "higher-latency"

Added the bit about "minimal difference in write latencies between ZONE and REGION survival due to a new custom non-blocking transaction protocol"

---

v21.1/choosing-a-multi-region-configuration.md, line 9 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

nit: the spacing seems a little compressed between this line and the next. Not sure if there's anything to do.

agreed, filed an issue against the recent site redesign: #9924

---

v21.1/choosing-a-multi-region-configuration.md, line 11 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

"single-region reads and write"

Same thing in the next option.

Updated

---

v21.1/choosing-a-multi-region-configuration.md, line 11 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

The "low-latency/high-latency" vs. "single-region/multi-region" distinctions are subtle. I wonder if there's anything better we could say here to distinguish them. Should we be using "from a single region"/"from all regions" to drive home the idea that we're talking about access performance? So something like:

you get zone survival, low-latency reads and writes from a single region, and low-latency stale reads from all other regions

you get region survival, low-latency reads from a single region, higher-latency writes from a single region, and low-latency stale reads from all other regions

... low-latency reads and writes from all regions

... low-latency reads from all regions and higher-latency writes from all regions

I like this way of framing it better. I revised each of the bullets in this section to use this language, and also to use a nested list for better scanning, e.g.

• change only survival goals: ... you get:
  • region survival
  • ...

Let me know what you think!

(Also, Adam - this means I ended up taking your suggestion after all to move the "this is useful for apps doing X" to the front, yay)

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

Should we use "move" instead of "upgrade" here as well?

Yes, updated.

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

It's confusing that we mention writes being slower in this option, but not in the "Change only survival goals" option.

We should either hint that writes are slower (independent of locality) for REGION survivability across this overview, or ignore it.

I agree. It's much clearer in the revised version because with everything in list form it's more scannable.

I added the hint to both of the REGION survival options.

---

v21.1/choosing-a-multi-region-configuration.md, line 24 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

nit: the first column is getting compressed

Oh man these narrow layouts!!!

Added a rather yucky div tag with inline CSS based on something I saw done in docs#9833

seems to be fixed now (tm)

yay markdown!!!!

---

v21.1/multiregion-overview.md, line 240 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

Should we reverse this order? We talk about ZONE vs. REGION before REGIONAL vs. GLOBAL everywhere else.

Agreed - swapped 'em!

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 16 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

It would be worth mentioning what we can survive with this setting - a single node failure up to an entire zone failure.

OK! Changed to "- 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."

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/08d7130fb2fef8bd4007a04af5ac5dec6810d849/

Edited pages:

• v21.1/choosing-a-multi-region-configuration.md
• v21.1/multiregion-overview.md
• v21.1/when-to-use-regional-vs-global-tables.md
• v21.1/when-to-use-zone-vs-region-survival-goals.md

[nvanbenschoten]

Reviewed 1 of 4 files at r3.
Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @ajstorm, @nvanbenschoten, and @rmloveland)

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Updated to say just that! (RBR + when you are writing to row whose home is also primary)

Actually, this doesn't have to do with the primary region at all. It's just if you are reading from or writing to a row from its home region.

In other words, the only different between this and the ZONE version is that writes are a little slower.

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

I agree. It's much clearer in the revised version because with everything in list form it's more scannable.

I added the hint to both of the REGION survival options.

This looks great!

---

v21.1/choosing-a-multi-region-configuration.md, line 18 at r3 (raw file):

- _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 and writes from a single region.

and writes

[rmloveland]

Thanks Nathan! Fixed the one thing about row's home vs. DB primary.

Reviewable status: complete! 0 of 0 LGTMs obtained (and 1 stale) (waiting on @ajstorm and @nvanbenschoten)

---

v21.1/choosing-a-multi-region-configuration.md, line 28 at r1 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

Actually, this doesn't have to do with the primary region at all. It's just if you are reading from or writing to a row from its home region.

In other words, the only different between this and the ZONE version is that writes are a little slower.

Updated to say "from its home region". Gosh I'm gonna start getting this right soon, I swear.

---

v21.1/choosing-a-multi-region-configuration.md, line 17 at r2 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

This looks great!

Thanks!

---

v21.1/choosing-a-multi-region-configuration.md, line 18 at r3 (raw file):

Previously, nvanbenschoten (Nathan VanBenschoten) wrote…

and writes

Done!

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/eef0de44eb6d7ee1e89fc5cfaf857b5004f712cc/

Edited pages:

• v21.1/choosing-a-multi-region-configuration.md
• v21.1/multiregion-overview.md
• v21.1/when-to-use-regional-vs-global-tables.md
• v21.1/when-to-use-zone-vs-region-survival-goals.md

[nvanbenschoten]

Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @ajstorm, @lnhsingh, and @nvanbenschoten)

[ajstorm]

Reviewable status: complete! 2 of 0 LGTMs obtained (waiting on @ajstorm, @lnhsingh, and @nvanbenschoten)

[lnhsingh]

but added some comments to annoy you, since you do that to me :)

Reviewable status: complete! 3 of 0 LGTMs obtained (waiting on @ajstorm, @nvanbenschoten, and @rmloveland)

---

v21.1/choosing-a-multi-region-configuration.md, line 36 at r4 (raw file):

- The types of applications that can benefit from each combination.

| <div style="width: 200px;"></div> locality &#8595; survival &#8594; | `ZONE`                                                                                                                                 | `REGION`                                                                                                                                                                                                             |

This might be a little easier to read if the info was in a bulleted list within the table cell (or if the locality headers merged across the two cells), but I assume you laid out the table the way you did so you didn't have to use HTML to create the list.

---

v21.1/when-to-use-regional-vs-global-tables.md, line 4 at r4 (raw file):

title: When to use REGIONAL vs. GLOBAL tables
summary: Learn how to use CockroachDB's improved multi-region user experience.
toc: true

For pages that don't have any headings other than See Also, should we remove the TOC? You don't have to change anything here, but maybe this is something I should bring up for the style guide

---

v21.1/when-to-use-regional-vs-global-tables.md, line 15 at r4 (raw file):

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

Part of me thinks that this info would be better in a table, that way you could combine the info above this ("The following table localities are available") and when you should use each type of table.

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 14 at r4 (raw file):

- `REGION`

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

Same comment here about maybe presenting this info as a table, but feel free to ignore!

[rmloveland]

Thanks Lauren! Your comments could never annoy me (well, probably) :-)

Reviewable status: complete! 3 of 0 LGTMs obtained (waiting on @ajstorm, @lnhsingh, and @nvanbenschoten)

---

v21.1/choosing-a-multi-region-configuration.md, line 36 at r4 (raw file):

Previously, lnhsingh (Lauren Hirata Singh) wrote…

This might be a little easier to read if the info was in a bulleted list within the table cell (or if the locality headers merged across the two cells), but I assume you laid out the table the way you did so you didn't have to use HTML to create the list.

Yes that's correct! I really wish Markdown (or whatever this is) had sane tables. Sorry it's so hard to read.

---

v21.1/when-to-use-regional-vs-global-tables.md, line 4 at r4 (raw file):

Previously, lnhsingh (Lauren Hirata Singh) wrote…

For pages that don't have any headings other than See Also, should we remove the TOC? You don't have to change anything here, but maybe this is something I should bring up for the style guide

I agree we should remove it - done here and on the other page where this was the case

---

v21.1/when-to-use-regional-vs-global-tables.md, line 15 at r4 (raw file):

Previously, lnhsingh (Lauren Hirata Singh) wrote…

Part of me thinks that this info would be better in a table, that way you could combine the info above this ("The following table localities are available") and when you should use each type of table.

All else being equal I tend to agree but I'm reluctant b/c using tables is so hard in markdown!

---

v21.1/when-to-use-zone-vs-region-survival-goals.md, line 14 at r4 (raw file):

Previously, lnhsingh (Lauren Hirata Singh) wrote…

Same comment here about maybe presenting this info as a table, but feel free to ignore!

I never ignore your comments!

But I am reluctant for the reason stated in my reply above

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/cedfe4fdf4775ad1be811f147b07ae926b721cef/

Edited pages:

• v21.1/choosing-a-multi-region-configuration.md
• v21.1/multiregion-overview.md
• v21.1/when-to-use-regional-vs-global-tables.md
• v21.1/when-to-use-zone-vs-region-survival-goals.md