-
Notifications
You must be signed in to change notification settings - Fork 455
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
1 parent
64d938b
commit 1745d73
Showing
10 changed files
with
425 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
22 changes: 22 additions & 0 deletions
22
_includes/v21.1/sql/generated/diagrams/alter_database_add_region.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
26 changes: 26 additions & 0 deletions
26
_includes/v21.1/sql/generated/diagrams/alter_database_survival_goal.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
28 changes: 28 additions & 0 deletions
28
_includes/v21.1/sql/generated/diagrams/alter_table_locality.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
--- | ||
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}} | ||
|
||
{{site.data.alerts.callout_danger}} | ||
In order to add a region with `ADD REGION`, you must first set a primary database region. For an example showing how to add a primary region, see [Set the primary region](#set-the-primary-region). | ||
{{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 foo 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 foo 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 foo; | ||
~~~ | ||
|
||
~~~ | ||
database | region | primary | zones | ||
-----------+----------+---------+------------------------------------------------ | ||
foo | 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 foo 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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.