Add docs for migrating to v21.1+ multiregion SQL

Fixes cockroachdb#11017

Summary of changes:

- Add a new page, 'Migrate to Multi-Region SQL', which has:

  - Mappings from each of the legacy replication-zone-based patterns and
    the newer multi-region SQL abstractions that are designed to replace
    them.

  - Instructions for migrating from replication-zone-based workflows to
    multi-region SQL abstractions.

  - A review of the zone configuration changes that result from running
    the multi-region SQL statements.

_includes/sidebar-data-v21.1.json

@@ -721,6 +721,12 @@
                   "/${VERSION}/data-domiciling.html"
                 ]
               },
+              {
+                "title": "Migrate to Multi-region SQL",
+                "urls": [
+                  "/${VERSION}/migrate-to-multiregion-sql.html"
+                ]
+              },
               {
                 "title": "Topology Patterns",
                 "items": [

_includes/v21.1/topology-patterns/see-also.md

@@ -3,6 +3,7 @@
 - [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)
 - [Multi-region SQL performance](demo-low-latency-multi-region-deployment.html)
+- [Migrate to Multi-region SQL](migrate-to-multiregion-sql.html)
 - [`ALTER DATABASE ... SURVIVE {ZONE,REGION} FAILURE`](survive-failure.html)
 - [`ALTER TABLE ... SET LOCALITY ...`](set-locality.html)
 - [Topology Patterns Overview](topology-patterns.html)

_includes/v21.1/zone-configs/variables.md

@@ -4,11 +4,11 @@ Variable | Description
 `range_max_bytes` | <a name="range-max-bytes"></a> The maximum size, in bytes, for a range of data in the zone. When a range reaches this size, CockroachDB will split it into two ranges.<br><br>**Default:** `536870912` (512 MiB)
 `gc.ttlseconds` | <a name="gc-ttlseconds"></a> The number of seconds overwritten values will be retained before garbage collection. Smaller values can save disk space if values are frequently overwritten; larger values increase the range allowed for `AS OF SYSTEM TIME` queries, also know as [Time Travel Queries](select-clause.html#select-historical-data-time-travel).<br><br>It is not recommended to set this below `600` (10 minutes); doing so will cause problems for long-running queries. Also, since all versions of a row are stored in a single range that never splits, it is not recommended to set this so high that all the changes to a row in that time period could add up to more than 512 MiB; such oversized ranges could contribute to the server running out of memory or other problems. {{site.data.alerts.callout_info}} Ensure that you set `gc.ttlseconds` long enough to accommodate your [backup schedule](create-schedule-for-backup.html), otherwise your incremental backups will fail with [this error](common-errors.html#protected-ts-verification-error). For example, if you set up your backup schedule to recur daily, but you set `gc.ttlseconds` to less than one day, all your incremental backups will fail.{{site.data.alerts.end}} **Default:** `90000` (25 hours)
 `num_replicas` | <a name="num_replicas"></a> The number of replicas in the zone.<br><br>**Default:** `3`<br><br>For the `system` database and `.meta`, `.liveness`, and `.system` ranges, the default value is `5`.<br /><br />For [multi-region databases configured to survive region failures](multiregion-overview.html#surviving-region-failures), the default value is `5`; this will include both [voting](#num_voters) and [non-voting replicas](architecture/replication-layer.html#non-voting-replicas).
-`constraints` | An array of required (`+`) and/or prohibited (`-`) constraints influencing the location of replicas. See [Types of Constraints](configure-replication-zones.html#types-of-constraints) and [Scope of Constraints](configure-replication-zones.html#scope-of-constraints) for more details.<br/><br/>To prevent hard-to-detect typos, constraints placed on [store attributes and node localities](configure-replication-zones.html#descriptive-attributes-assigned-to-nodes) must match the values passed to at least one node in the cluster. If not, an error is signalled. To prevent this error, make sure at least one active node is configured to match the constraint. For example, apply `constraints = '[+region=west]'` only if you had set `--locality=region=west` for at least one node while starting the cluster.<br/><br/>**Default:** No constraints, with CockroachDB locating each replica on a unique node and attempting to spread replicas evenly across localities.
+`constraints` | <a name="constraints"></a> An array of required (`+`) and/or prohibited (`-`) constraints influencing the location of replicas. See [Types of Constraints](configure-replication-zones.html#types-of-constraints) and [Scope of Constraints](configure-replication-zones.html#scope-of-constraints) for more details.<br/><br/>To prevent hard-to-detect typos, constraints placed on [store attributes and node localities](configure-replication-zones.html#descriptive-attributes-assigned-to-nodes) must match the values passed to at least one node in the cluster. If not, an error is signalled. To prevent this error, make sure at least one active node is configured to match the constraint. For example, apply `constraints = '[+region=west]'` only if you had set `--locality=region=west` for at least one node while starting the cluster.<br/><br/>**Default:** No constraints, with CockroachDB locating each replica on a unique node and attempting to spread replicas evenly across localities.
 `lease_preferences` <a name="lease_preferences"></a> | An ordered list of required and/or prohibited constraints influencing the location of [leaseholders](architecture/overview.html#glossary).  Whether each constraint is required or prohibited is expressed with a leading `+` or `-`, respectively.  Note that lease preference constraints do not have to be shared with the `constraints` field.  For example, it's valid for your configuration to define a `lease_preferences` field that does not reference any values from the `constraints` field.  It's also valid to define a `lease_preferences` field with no `constraints` field at all. <br /><br />  If the first preference cannot be satisfied, CockroachDB will attempt to satisfy the second preference, and so on.  If none of the preferences can be met, the lease will be placed using the default lease placement algorithm, which is to base lease placement decisions on how many leases each node already has, trying to make all the nodes have around the same amount.<br /><br />Each value in the list can include multiple constraints.  For example, the list `[[+zone=us-east-1b, +ssd], [+zone=us-east-1a], [+zone=us-east-1c, +ssd]]` means "prefer nodes with an SSD in `us-east-1b`, then any nodes in `us-east-1a`, then nodes in `us-east-1c` with an SSD."<br /><br /> For a usage example, see [Constrain leaseholders to specific availability zones](configure-replication-zones.html#constrain-leaseholders-to-specific-availability-zones).<br /><br />**Default**: No lease location preferences are applied if this field is not specified.
-`global_reads` | <span class="version-tag">New in v21.1:</span> If `true`, transactions operating on the range(s) affected by this zone config should be non-blocking. Most users will not need to modify this setting; it is applied automatically when you [use the `GLOBAL` table locality in a multi-region cluster](multiregion-overview.html#table-locality).
+`global_reads` | <a name="global_reads"></a> <span class="version-tag">New in v21.1:</span> If `true`, transactions operating on the range(s) affected by this zone config should be [non-blocking](architecture/transaction-layer.html#non-blocking-transactions), which slows down writes but allows reads from any replica in the range. Most users will not need to modify this setting; it is applied automatically when you [use the `GLOBAL` table locality in a multi-region cluster](global-tables.html).
 `num_voters` | <a name="num_voters"></a> Specifies the number of [voting replicas](architecture/life-of-a-distributed-transaction.html#consensus). When set, `num_replicas` will be the sum of voting and [non-voting replicas](architecture/replication-layer.html#non-voting-replicas). Most users will not need to modify this setting; it is part of the underlying machinery that enables [improved multi-region capabilities in v21.1 and above](multiregion-overview.html).
-`voter_constraints` | <span class="version-tag">New in v21.1:</span> Specifies the constraints that govern the placement of voting replicas. This differs from the `constraints` field, which will govern the placement of all voting and non-voting replicas. Most users will not need to modify this setting; it is part of the underlying machinery that enables [improved multi-region capabilities in v21.1 and above](multiregion-overview.html).
+`voter_constraints` | <a name="voter_constraints"></a> <span class="version-tag">New in v21.1:</span> Specifies the constraints that govern the placement of voting replicas. This differs from the `constraints` field, which will govern the placement of all voting and non-voting replicas. Most users will not need to modify this setting; it is part of the underlying machinery that enables [improved multi-region capabilities in v21.1 and above](multiregion-overview.html).
 
 {{site.data.alerts.callout_info}}
 If a value is not set, new zone configurations will inherit their values from their parent zone (e.g., a partition zone inherits from the table zone), which is not necessarily `default`.

v21.1/demo-low-latency-multi-region-deployment.md

@@ -444,5 +444,6 @@ The small demo cluster used in this example is essentially in a state of overloa
 - [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)
 - [When to use `REGIONAL` vs. `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)
+- [Migrate to Multi-region SQL](migrate-to-multiregion-sql.html)
 - [Reads and Writes in CockroachDB](architecture/reads-and-writes-overview.html)
 - [Install CockroachDB](install-cockroachdb.html)