Add SQL docs for survival, region, table locality

Summary of changes:

- Add docs for ALTER TABLE .. SET LOCALITY {REGIONAL,GLOBAL}

- Add docs for ALTER DATABASE .. ADD REGION (also PRIMARY REGION)

- Add docs for ALTER DATABASE .. SURVIVE {REGION,ZONE} FAILURE

- Edit the 'Multi-region Overview' page to point users to the SQL
  reference pages above for syntax examples

Fixes #9096
Fixes #9115
Fixes #9298
Fixes #9301
Fixes #9598
Fixes #9610
Fixes #9617

Addresses #9341
Addresses #9708
Addresses #9709
Addresses #9884
Addresses #9886

_includes/sidebar-data-v21.1.json

@@ -1221,6 +1221,12 @@
  "/${VERSION}/add-constraint.html"
  ]
  },
+ {
+ "title": "<code>ADD REGION</code>",
+ "urls": [
+ "/${VERSION}/add-region.html"
+ ]
+ },
  {
  "title": "<code>ALTER COLUMN</code>",
  "urls": [
@@ -1749,6 +1755,12 @@
  "/${VERSION}/set-cluster-setting.html"
  ]
  },
+ {
+ "title": "<code>SET LOCALITY</code>",
+ "urls": [
+ "/${VERSION}/set-locality.html"
+ ]
+ },
  {
  "title": "<code>SET SCHEMA</code>",
  "urls": [
@@ -1941,6 +1953,12 @@
  "/${VERSION}/split-at.html"
  ]
  },
+ {
+ "title": "<code>SURVIVE {ZONE,REGION} FAILURE</code>",
+ "urls": [
+ "/${VERSION}/survive-failure.html"
+ ]
+ },
  {
  "title": "<code>TRUNCATE</code>",
  "urls": [

_includes/v21.1/sql/generated/diagrams/alter_database_add_region.html

@@ -0,0 +1,22 @@
+<div><svg width="663" height="37">
+<polygon points="9 17 1 13 1 21"></polygon>
+<polygon points="17 17 9 13 9 21"></polygon>
+<rect x="31" y="3" width="62" height="32" rx="10"></rect>
+<rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="39" y="21">ALTER</text>
+<rect x="113" y="3" width="92" height="32" rx="10"></rect>
+<rect x="111" y="1" width="92" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="121" y="21">DATABASE</text><a xlink:href="sql-grammar.html#database_name" xlink:title="database_name">
+<rect x="225" y="3" width="124" height="32"></rect>
+<rect x="223" y="1" width="124" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="233" y="21">database_name</text></a><rect x="369" y="3" width="48" height="32" rx="10"></rect>
+<rect x="367" y="1" width="48" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="377" y="21">ADD</text>
+<rect x="437" y="3" width="74" height="32" rx="10"></rect>
+<rect x="435" y="1" width="74" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="445" y="21">REGION</text>
+<rect x="531" y="3" width="104" height="32"></rect>
+<rect x="529" y="1" width="104" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="539" y="21">region_name</text><path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m0 0 h10 m92 0 h10 m0 0 h10 m124 0 h10 m0 0 h10 m48 0 h10 m0 0 h10 m74 0 h10 m0 0 h10 m104 0 h10 m3 0 h-3"></path>
+<polygon points="653 17 661 13 661 21"></polygon>
+<polygon points="653 17 645 13 645 21"></polygon></svg></div>

_includes/v21.1/sql/generated/diagrams/alter_database_survival_goal.html

@@ -0,0 +1,26 @@
+<div><svg width="709" height="81">
+<polygon points="9 17 1 13 1 21"></polygon>
+<polygon points="17 17 9 13 9 21"></polygon>
+<rect x="31" y="3" width="62" height="32" rx="10"></rect>
+<rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="39" y="21">ALTER</text>
+<rect x="113" y="3" width="92" height="32" rx="10"></rect>
+<rect x="111" y="1" width="92" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="121" y="21">DATABASE</text><a xlink:href="sql-grammar.html#database_name" xlink:title="database_name">
+<rect x="225" y="3" width="124" height="32"></rect>
+<rect x="223" y="1" width="124" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="233" y="21">database_name</text></a><rect x="369" y="3" width="80" height="32" rx="10"></rect>
+<rect x="367" y="1" width="80" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="377" y="21">SURVIVE</text>
+<rect x="489" y="3" width="58" height="32" rx="10"></rect>
+<rect x="487" y="1" width="58" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="497" y="21">ZONE</text>
+<rect x="489" y="47" width="74" height="32" rx="10"></rect>
+<rect x="487" y="45" width="74" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="497" y="65">REGION</text>
+<rect x="603" y="3" width="78" height="32" rx="10"></rect>
+<rect x="601" y="1" width="78" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="611" y="21">FAILURE</text>
+<path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m0 0 h10 m92 0 h10 m0 0 h10 m124 0 h10 m0 0 h10 m80 0 h10 m20 0 h10 m58 0 h10 m0 0 h16 m-114 0 h20 m94 0 h20 m-134 0 q10 0 10 10 m114 0 q0 -10 10 -10 m-124 10 v24 m114 0 v-24 m-114 24 q0 10 10 10 m94 0 q10 0 10 -10 m-104 10 h10 m74 0 h10 m20 -44 h10 m78 0 h10 m3 0 h-3"></path>
+<polygon points="699 17 707 13 707 21"></polygon>
+<polygon points="699 17 691 13 691 21"></polygon></svg></div>

_includes/v21.1/sql/generated/diagrams/alter_table_locality.html

@@ -0,0 +1,28 @@
+<div><svg width="669" height="135">
+<polygon points="9 17 1 13 1 21"></polygon>
+<polygon points="17 17 9 13 9 21"></polygon>
+<rect x="31" y="3" width="62" height="32" rx="10"></rect>
+<rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="39" y="21">ALTER</text>
+<rect x="113" y="3" width="62" height="32" rx="10"></rect>
+<rect x="111" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="121" y="21">TABLE</text>
+<rect x="215" y="35" width="34" height="32" rx="10"></rect>
+<rect x="213" y="33" width="34" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="223" y="53">IF</text>
+<rect x="269" y="35" width="70" height="32" rx="10"></rect>
+<rect x="267" y="33" width="70" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="277" y="53">EXISTS</text><a xlink:href="sql-grammar.html#table_name" xlink:title="table_name">
+<rect x="379" y="3" width="96" height="32"></rect>
+<rect x="377" y="1" width="96" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="387" y="21">table_name</text></a><rect x="495" y="3" width="44" height="32" rx="10"></rect>
+<rect x="493" y="1" width="44" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="503" y="21">SET</text>
+<rect x="559" y="3" width="88" height="32" rx="10"></rect>
+<rect x="557" y="1" width="88" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="567" y="21">LOCALITY</text>
+<rect x="577" y="101" width="64" height="32"></rect>
+<rect x="575" y="99" width="64" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="585" y="119">locality</text><path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m0 0 h10 m62 0 h10 m20 0 h10 m0 0 h134 m-164 0 h20 m144 0 h20 m-184 0 q10 0 10 10 m164 0 q0 -10 10 -10 m-174 10 v12 m164 0 v-12 m-164 12 q0 10 10 10 m144 0 q10 0 10 -10 m-154 10 h10 m34 0 h10 m0 0 h10 m70 0 h10 m20 -32 h10 m96 0 h10 m0 0 h10 m44 0 h10 m0 0 h10 m88 0 h10 m2 0 l2 0 m2 0 l2 0 m2 0 l2 0 m-114 98 l2 0 m2 0 l2 0 m2 0 l2 0 m2 0 h10 m64 0 h10 m3 0 h-3"></path>
+<polygon points="659 115 667 111 667 119"></polygon>
+<polygon points="659 115 651 111 651 119"></polygon></svg></div>

v21.1/add-region.md

@@ -0,0 +1,109 @@
+---
+title: ADD REGION
+summary: The ADD REGION statement adds a region to a multi-region database.
+toc: true
+---
+
+<span class="version-tag">New in v21.1:</span> The `ALTER DATABASE .. ADD REGION` [statement](sql-statements.html) adds a [region](multiregion-overview.html#database-regions) to a [multi-region database](multiregion-overview.html).
+
+{{site.data.alerts.callout_info}}
+`ADD REGION` is a subcommand of [`ALTER DATABASE`](alter-database.html)
+{{site.data.alerts.end}}
+
+## Synopsis
+
+<div>
+ {% include {{ page.version.version }}/sql/generated/diagrams/alter_database_add_region.html %}
+</div>
+
+## Parameters
+
+| Parameter | Description |
+|-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `database_name` | The database you are adding a [region](multiregion-overview.html#database-regions) to. |
+| `region_name` | The [region](multiregion-overview.html#database-regions) being added to this database. Allowed values include any region added at [node startup](cockroach-start.html#locality). |
+
+## Required privileges
+
+The user must be a member of [the `admin` role](authorization.html) or must have the [`CREATEDB`](create-role.html#create-a-role-that-can-create-and-rename-databases) parameter set.
+
+## Examples
+
+### Set the primary region
+
+To add the first region, or to set an already-added region as the primary region, use the following statement:
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE {db} PRIMARY REGION "us-east1";
+~~~
+
+~~~
+ALTER DATABASE PRIMARY REGION
+~~~
+
+For more information, see [Database regions](multiregion-overview.html#database-regions).
+
+### Add a region to a database
+
+To add another region to a database that already has at least one region, use a statement like the following:
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER database {db} ADD region "us-east1";
+~~~
+
+~~~
+ALTER DATABASE ADD REGION
+~~~
+
+For more information, see [Database regions](multiregion-overview.html#database-regions).
+
+{{site.data.alerts.callout_info}}
+You can only add regions to a multi-region database that were defined at node startup time. For more information, see [Cluster regions](multiregion-overview.html#cluster-regions).
+{{site.data.alerts.end}}
+
+### View a database's regions
+
+To view the regions associated with a multi-region database, use the following statement:
+
+{% include copy-clipboard.html %}
+~~~ sql
+SHOW REGIONS FROM DATABASE {db};
+~~~
+
+~~~
+ database | region | primary | zones
+-----------+----------+---------+------------------------------------------------
+ {db} | us-east1 | true | {us-east1-b,us-east1-b,us-east1-b,us-east1-b}
+(1 row)
+~~~
+
+For more information, see [Database regions](multiregion-overview.html#database-regions).
+
+### Drop a region from a database
+
+To drop a region from a multi-region database, use the following statement:
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE {db} DROP REGION "us-east1";
+~~~
+
+~~~
+ALTER DATABASE DROP REGION
+~~~
+
+You can not drop the primary region from a multi-region database. If you want to drop the current primary region, you must designate a new primary region first.
+
+{{site.data.alerts.callout_danger}}
+A multi-region database must have at least one region. If you try to drop the only remaining database region, an error will be signalled.
+{{site.data.alerts.end}}
+
+For more information, see [Database regions](multiregion-overview.html#database-regions).
+
+## See also
+
+- [Multi-region overview](multiregion-overview.html)
+- [`ALTER TABLE`](alter-table.html)
+- [Other SQL Statements](sql-statements.html)

v21.1/alter-database.md

@@ -16,6 +16,8 @@ Subcommand | Description
 [`CONVERT TO SCHEMA`](convert-to-schema.html) | Convert a [database](create-database.html) to a [schema](sql-name-resolution.html).
 [`OWNER TO`](owner-to.html) | Change the owner of a database.
 [`RENAME`](rename-database.html) | Change the name of a database.
+[`ADD REGION`](add-region.html) | <span class="version-tag">New in v21.1:</span> Add a region to a [multi-region database](multiregion-overview.html).
+[`SURVIVE {ZONE,REGION} FAILURE`](survive-failure.html) | <span class="version-tag">New in v21.1:</span> Add a survival goal to a [multi-region database](multiregion-overview.html).
 
 ## Viewing schema changes
 

v21.1/alter-table.md

@@ -32,6 +32,7 @@ Subcommand | Description | Can combine with other subcommands?
 [`SPLIT AT`](split-at.html) | Force a range split at the specified row in the table. | No
 [`UNSPLIT AT`](unsplit-at.html) | Remove a range split enforcement at a specified row in the table. | No
 [`VALIDATE CONSTRAINT`](validate-constraint.html) | Check whether values in a column match a [constraint](constraints.html) on the column. | Yes
+[`SET LOCALITY {REGIONAL, GLOBAL}`](set-locality.html) | <span class="version-tag">New in v21.1:</span> Set the table locality for a table in a [multi-region database](multiregion-overview.html). | No
 
 ## Viewing schema changes
 

v21.1/multiregion-overview.md

@@ -57,28 +57,13 @@ SHOW REGIONS FROM CLUSTER;
 
  _Database regions_ are a high-level abstraction for a geographic region. Each region is broken into multiple zones. These terms are meant to correspond directly to the region and zone terminology used by cloud providers.
 
-The regions added during node startup become _Database Regions_ when they are added to a database using the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER DATABASE <db> PRIMARY REGION 'us-east-1';
-~~~
+The regions added during node startup become _Database Regions_ when they are added to a database. To add the first region, use the [`ALTER DATABASE .. PRIMARY REGION` statement](add-region.html#set-the-primary-region).
 
 While the database has only one region assigned to it, it is considered a "multi-region database." This means that all data in that database is stored within its assigned regions, and CockroachDB optimizes access to the database's data from the primary region.
 
-To add another database region, use a statement like the following:
+To add another database region, use the [`ALTER DATABASE .. ADD REGION` statement](add-region.html#add-a-region-to-a-database).
 
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER DATABASE <db> ADD REGION 'us-west-1';
-~~~
-
-To show all of a database's regions, execute the following SQL statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-SHOW REGIONS FROM DATABASE <db>;
-~~~
+To show all of a database's regions, execute the [`SHOW REGIONS FROM DATABASE` statement](add-region.html#view-a-databases-regions).
 
 {{site.data.alerts.callout_info}}
 If the default _Survival Goals_ and _Table Localities_ meet your needs, there is nothing else you need to do once you have set a database's primary region.
@@ -109,6 +94,8 @@ For more information about the survival goals supported by CockroachDB, see the
 
 With the zone level survival goal, the database will remain fully available for reads and writes, even if a zone goes down. However, the database may not remain fully available if multiple zones fail in the same region.
 
+You can configure a database to survive zone failures using the [`ALTER DATABASE .. SURVIVE ZONE FAILURE` statement](survive-failure.html).
+
 {{site.data.alerts.callout_info}}
 Surviving zone failures is the default setting for multi-region databases.
 
@@ -119,12 +106,7 @@ If your application has performance or availability needs that are different tha
 
 The region level survival goal has the property that the database will remain fully available for reads and writes, even if an entire region goes down. This added survival comes at a 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. In other words, you are adding network hops and making writes slower in exchange for robustness.
 
-You can upgrade a database to survive region failures using the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER DATABASE <db> SURVIVE REGION FAILURE;
-~~~
+You can configure a database to survive region failures using the [`ALTER DATABASE .. SURVIVE REGION FAILURE` statement](survive-failure.html).
 
 {{site.data.alerts.callout_info}}
 In order to survive region failures, you must have added at least 3 [database regions](#database-regions)
@@ -156,19 +138,7 @@ Regional tables work well when your application requires low-latency reads and w
 
 For _regional_ tables, access to the table will be fast in the table's "home region" and slower in other regions. In other words, CockroachDB optimizes access to data in regional tables from a single region. By default, a regional table's home region is the [database's primary region](#database-regions), but that can be changed to use any region added to the database.
 
-To optimize read and write access to the data in a table from the primary region, use the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER TABLE <table> SET LOCALITY REGIONAL BY TABLE IN PRIMARY REGION;
-~~~
-
-To optimize read and write access to the data in a table from the `us-east-1` region, use the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER TABLE <table> SET LOCALITY REGIONAL BY TABLE IN 'us-east-1';
-~~~
+For instructions showing how to set a table's locality to `REGIONAL BY TABLE`, see [`ALTER TABLE .. SET LOCALITY`](set-locality.html#regional-by-table)
 
 {{site.data.alerts.callout_info}}
 By default, all tables in a multi-region database are _regional_ tables that use the database's primary region. Unless you know your application needs different performance characteristics than regional tables provide, there is no need to change this setting.
@@ -182,39 +152,7 @@ Use regional by row tables when your application requires low-latency reads and
 
 For an example of a table that can benefit from the _regional by row_ setting in a multi-region deployment, see the `users` table from the [MovR application](movr.html).
 
-To make an existing table a _regional by row_ table, use the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER TABLE <table> SET LOCALITY REGIONAL BY ROW;
-~~~
-
-Every row in a regional by row table has a hidden `crdb_region` column that represents the row's home region. To see a row's region, issue a statement like the following:
-
-{% include copy-clipboard.html %}
-~~~ sql
-SELECT crdb_region, id FROM <table>;
-~~~
-
-To update an existing row's home region, use an [`UPDATE`](update.html) statement like the following:
-
-{% include copy-clipboard.html %}
-~~~ sql
-UPDATE <table> SET crdb_region = 'eu-west' WHERE id IN (...)
-~~~
-
-To add a new row to a regional by row table, you must choose one of the following options.
-
-- Let CockroachDB set the row's home region automatically. It will use the region of the gateway node from which the row is inserted.
-
-- Set the home region explicitly using an [`INSERT`](insert.html) statement like the following:
-
- {% include copy-clipboard.html %}
- ~~~ sql
- INSERT INTO <table> (crdb_region, ...) VALUES ('us-east-1', ...);
- ~~~
-
-This is necessary because every row in a regional by row table must have a home region.
+For instructions showing how to set a table's locality to `REGIONAL BY ROW`, see [`ALTER TABLE .. SET LOCALITY`](set-locality.html#regional-by-row)
 
 ### Global tables
 
@@ -224,12 +162,7 @@ Use global tables when your application has a "read-mostly" table of reference d
 
 For an example of a table that can benefit from the _global_ table locality setting in a multi-region deployment, see the `promo_codes` table from the [MovR application](movr.html).
 
-To optimize read access to the data in a table from any region (that is, globally), use the following statement:
-
-{% include copy-clipboard.html %}
-~~~ sql
-ALTER TABLE <table> SET LOCALITY GLOBAL;
-~~~
+For instructions showing how to set a table's locality to `GLOBAL`, see [`ALTER TABLE .. SET LOCALITY`](set-locality.html#global)
 
 ## Choosing a multi-region configuration