Merge pull request #10465 from cockroachdb/20210422-multiregion-capab…

…ilities

Add global and regional tables to patterns docs

_includes/sidebar-data-v21.1.json

@@ -638,10 +638,10 @@
             ]
           },
           {
-            "title": "Multi-region Clusters",
+            "title": "Multi-region Capabilities",
             "items": [
               {
-                "title": "Multi-region Overview",
+                "title": "Overview",
                 "urls": [
                   "/${VERSION}/multiregion-overview.html"
                 ]
@@ -663,58 +663,52 @@
                 "urls": [
                   "/${VERSION}/when-to-use-regional-vs-global-tables.html"
                 ]
-              }
-            ]
-          },
-          {
-            "title": "Topology Patterns",
-            "items": [
-              {
-                "title": "Overview",
-                "urls": [
-                  "/${VERSION}/topology-patterns.html"
-                ]
-              },
-              {
-                "title": "Development",
-                "urls": [
-                  "/${VERSION}/topology-development.html"
-                ]
-              },
-              {
-                "title": "Basic Production",
-                "urls": [
-                  "/${VERSION}/topology-basic-production.html"
-                ]
-              },
-              {
-                "title": "Geo-Partitioned Replicas",
-                "urls": [
-                  "/${VERSION}/topology-geo-partitioned-replicas.html"
-                ]
-              },
-              {
-                "title": "Geo-Partitioned Leaseholders",
-                "urls": [
-                  "/${VERSION}/topology-geo-partitioned-leaseholders.html"
-                ]
-              },
-              {
-                "title": "Duplicate Indexes",
-                "urls": [
-                  "/${VERSION}/topology-duplicate-indexes.html"
-                ]
-              },
-              {
-                "title": "Follower Reads",
-                "urls": [
-                  "/${VERSION}/topology-follower-reads.html"
-                ]
               },
               {
-                "title": "Follow-the-Workload",
-                "urls": [
-                  "/${VERSION}/topology-follow-the-workload.html"
+                "title": "Topology Patterns",
+                "items": [
+                  {
+                    "title": "Overview",
+                    "urls": [
+                      "/${VERSION}/topology-patterns.html"
+                    ]
+                  },
+                  {
+                    "title": "Development",
+                    "urls": [
+                      "/${VERSION}/topology-development.html"
+                    ]
+                  },
+                  {
+                    "title": "Basic Production",
+                    "urls": [
+                      "/${VERSION}/topology-basic-production.html"
+                    ]
+                  },
+                  {
+                    "title": "Regional Tables",
+                    "urls": [
+                      "/${VERSION}/regional-tables.html"
+                    ]
+                  },
+                  {
+                    "title": "Global Tables",
+                    "urls": [
+                      "/${VERSION}/global-tables.html"
+                    ]
+                  },
+                  {
+                    "title": "Follower Reads",
+                    "urls": [
+                      "/${VERSION}/topology-follower-reads.html"
+                    ]
+                  },
+                  {
+                    "title": "Follow-the-Workload",
+                    "urls": [
+                      "/${VERSION}/topology-follow-the-workload.html"
+                    ]
+                  }
                 ]
               }
             ]

_includes/v21.1/misc/enterprise-features.md

@@ -1,10 +1,9 @@
 Feature | Description
 --------+-------------------------
-[Geo-Partitioning](topology-geo-partitioned-replicas.html) | This feature gives you row-level control of how and where your data is stored to dramatically reduce read and write latencies and assist in meeting regulatory requirements in multi-region deployments.
+[Multi-Region Capabilities](multiregion-overview.html) | This feature gives you row-level control of how and where your data is stored to dramatically reduce read and write latencies and assist in meeting regulatory requirements in multi-region deployments.
 [Follower Reads](follower-reads.html) | This feature reduces read latency in multi-region deployments by using the closest replica at the expense of reading slightly historical data.
 [`BACKUP`](backup.html) | This feature creates backups of your cluster's schema and data that are consistent as of a given timestamp, stored on a service such as AWS S3, Google Cloud Storage, NFS, or HTTP storage.<br><br>[Incremental backups](take-full-and-incremental-backups.html), [backups with revision history](take-backups-with-revision-history-and-restore-from-a-point-in-time.html), [locality-aware backups](take-and-restore-locality-aware-backups.html), and [encrypted backups](take-and-restore-encrypted-backups.html) require an enterprise license. [Full backups](take-full-and-incremental-backups.html) do not require an enterprise license.
 [Changefeeds into a Configurable Sink](create-changefeed.html) | This feature targets an allowlist of tables. For every change, it emits a record to a configurable sink, either Apache Kafka or a cloud-storage sink, for downstream processing such as reporting, caching, or full-text indexing.
 [Node Map](enable-node-map.html) | This feature visualizes the geographical configuration of a cluster by plotting node localities on a world map.
-[Locality-Aware Index Selection](cost-based-optimizer.html#preferring-the-nearest-index) | Given [multiple identical indexes](topology-duplicate-indexes.html) that have different locality constraints using [replication zones](configure-replication-zones.html), the cost-based optimizer will prefer the index that is closest to the gateway node that is planning the query. In multi-region deployments, this can lead to performance improvements due to improved data locality and reduced network traffic.
 [Encryption at Rest](encryption.html#encryption-at-rest-enterprise) | Supplementing CockroachDB's encryption in flight capabilities, this feature provides transparent encryption of a node's data on the local disk. It allows encryption of all files on disk using AES in counter mode, with all key sizes allowed.
 [GSSAPI with Kerberos Authentication](gssapi_authentication.html) | CockroachDB supports the Generic Security Services API (GSSAPI) with Kerberos authentication, which lets you use an external enterprise directory system that supports Kerberos, such as Active Directory.

_includes/v21.1/sql/global-table-description.md

@@ -0,0 +1,7 @@
+ _Global_ tables are optimized for low-latency reads from every region in the database. The tradeoff is that writes 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.
+
+Use global tables when your application has a "read-mostly" table of reference data that is rarely updated, and needs to be available to all regions.
+
+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).
+
+For instructions showing how to set a table's locality to `GLOBAL`, see [`ALTER TABLE ... SET LOCALITY`](set-locality.html#global)

_includes/v21.1/sql/locality-optimized-search.md

@@ -0,0 +1 @@
+Note that there is a performance benefit for queries that select a single row (e.g., `SELECT * FROM users WHERE email = 'anemailaddress@gmail.com'`). If `'anemailaddress@gmail.com'` is found in the local region, there is no need to search remote regions. This feature, whereby the SQL engine will avoid sending requests to nodes in other regions when it can read a value from a unique column that is stored locally, is known as _locality optimized search_.

_includes/v21.1/sql/regional-by-row-table-description.md

@@ -0,0 +1,7 @@
+In _regional by row_ tables, individual rows are optimized for access from different regions. This setting automatically divides a table and all of [its indexes](multiregion-overview.html#indexes-on-regional-by-row-tables) into [partitions](partitioning.html), with each partition optimized for access from a different region. Like [regional tables](multiregion-overview.html#regional-tables), _regional by row_ tables are optimized for access from a single region. However, that region is specified at the row level instead of applying to the whole table.
+
+Use regional by row tables when your application requires low-latency reads and writes at a row level where individual rows are primarily accessed from a single region. For example, a users table in a global application may need to keep some users' data in specific regions for better performance.
+
+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).
+
+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)

_includes/v21.1/sql/regional-table-description.md

@@ -0,0 +1,9 @@
+Regional tables work well when your application requires low-latency reads and writes for an entire table from a single region.
+
+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](multiregion-overview.html#database-regions), but that can be changed to use any region in the database.
+
+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.
+{{site.data.alerts.end}}

_includes/v21.1/sql/use-multiregion-instead-of-partitioning.md

@@ -0,0 +1,3 @@
+{{site.data.alerts.callout_success}}
+<span class="version-tag">New in v21.1:</span> Most users should not need to use partitioning directly.  Instead, they should use CockroachDB's built-in [multi-region capabilities](multiregion-overview.html), which automatically handle geo-partitioning and other low-level details.
+{{site.data.alerts.end}}

_includes/v21.1/topology-patterns/fundamentals.md

@@ -1,4 +1,4 @@
-- Multi-region topology patterns are almost always table-specific. If you haven't already, [review the full range of patterns](topology-patterns.html#multi-region-patterns) to ensure you choose the right one for each of your tables.
+- Multi-region topology patterns are almost always table-specific. If you haven't already, [review the full range of patterns](topology-patterns.html#multi-region) to ensure you choose the right one for each of your tables.
 - Review how data is replicated and distributed across a cluster, and how this affects performance. It is especially important to understand the concept of the "leaseholder". For a summary, see [Reads and Writes in CockroachDB](architecture/reads-and-writes-overview.html). For a deeper dive, see the [CockroachDB Architecture](architecture/overview.html) documentation.
 - Review the concept of [locality](cockroach-start.html#locality), which makes CockroachDB aware of the location of nodes and able to intelligently place and balance data based on how you define [replication controls](configure-replication-zones.html).
 - Review the recommendations and requirements in our [Production Checklist](recommended-production-settings.html).

_includes/v21.1/topology-patterns/multi-region-cluster-setup.md

@@ -1,28 +1,26 @@
-Each [multi-region topology pattern](topology-patterns.html#multi-region-patterns) assumes the following setup:
+Each [multi-region pattern](topology-patterns.html#multi-region) assumes the following setup:
 
 <img src="{{ 'images/v21.1/topology-patterns/topology_multi-region_hardware.png' | relative_url }}" alt="Multi-region hardware setup" style="max-width:100%" />
 
 #### Hardware
 
 - 3 regions
-
 - Per region, 3+ AZs with 3+ VMs evenly distributed across them
-
 - Region-specific app instances and load balancers
     - Each load balancer redirects to CockroachDB nodes in its region.
     - When CockroachDB nodes are unavailable in a region, the load balancer redirects to nodes in other regions.
 
 #### Cluster
 
-Each node is started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination. For example, the following command starts a node in the west1 AZ of the us-west region:
+Each node is started with the [`--locality`](cockroach-start.html#locality) flag specifying its region and AZ combination. For example, the following command starts a node in the `west1` AZ of the `us-west` region:
 
 {% include copy-clipboard.html %}
 ~~~ shell
 $ cockroach start \
 --locality=region=us-west,zone=west1 \
 --certs-dir=certs \
 --advertise-addr=<node1 internal address> \
---join=<node1 internal address>:26257,<node2 internal address>:26257,<node3 internal address>:26257 \        
+--join=<node1 internal address>:26257,<node2 internal address>:26257,<node3 internal address>:26257 \
 --cache=.25 \
 --max-sql-memory=.25 \
 --background

_includes/v21.1/topology-patterns/multiregion-db-setup.md

@@ -0,0 +1,36 @@
+First, create a database and set it as the default database:
+
+{% include copy-clipboard.html %}
+~~~ sql
+CREATE DATABASE test;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+USE test;
+~~~
+
+[This cluster is already deployed across three regions](#cluster-setup).  Therefore, to make this database a "multi-region database", you need to issue the following SQL statement that [sets the primary region](add-region.html#set-the-primary-region):
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE test PRIMARY REGION "us-east";
+~~~
+
+{{site.data.alerts.callout_info}}
+Every multi-region database must have a primary region.  For more information, see [Database regions](multiregion-overview.html#database-regions).
+{{site.data.alerts.end}}
+
+Next, issue the following [`ADD REGION`](add-region.html) statements to add the remaining regions to the database.
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE test ADD REGION "us-west";
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+ALTER DATABASE test ADD REGION "us-central";
+~~~
+
+Congratulations, `test` is now a multi-region database!

_includes/v21.1/topology-patterns/multiregion-fundamentals.md

@@ -0,0 +1,22 @@
+Multi-region patterns require thinking about the following questions:
+
+- What are my [survival goals](multiregion-overview.html#survival-goals)?  Do I need to survive a [zone failure](multiregion-overview.html#surviving-zone-failures)?  A [region failure](multiregion-overview.html#surviving-region-failures)?
+- What are the [table localities](multiregion-overview.html#table-locality) that will provide the performance characteristics I need for each table's data?
+  - Do I need low-latency reads and writes from a single region? Do I need that single region to be configurable at the [row level](multiregion-overview.html#regional-by-row-tables)?  Or will [a single optimized region for the entire table](multiregion-overview.html#regional-tables) suffice?
+  - Do I have a "read-mostly" [table of reference data that is rarely updated](multiregion-overview.html#global-tables), but that must be read with low latency from all regions?
+
+For more information about our multi-region capabilities, review the following pages:
+
+- [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)
+- [When to use `REGIONAL` vs. `GLOBAL` Tables](when-to-use-regional-vs-global-tables.html)
+
+In addition, reviewing the following information will be helpful:
+
+- The concept of [locality](cockroach-start.html#locality), which CockroachDB uses to intelligently place and balance data based on how you define the following settings:
+  - [Survival Goals](multiregion-overview.html#survival-goals)
+  - [Table Localities](multiregion-overview.html#table-locality)
+- The recommendations in our [Production Checklist](recommended-production-settings.html).
+- This page doesn't account for hardware specifications, so be sure to follow our [hardware recommendations](recommended-production-settings.html#hardware) and perform a POC to size hardware for your use case.
+- Finally, adopt these [SQL Best Practices](performance-best-practices-overview.html) to get good performance.

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

@@ -1,11 +1,14 @@
+- [Multi-Region Capabilities 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)
+- [When to use `REGIONAL` vs. `GLOBAL` tables](when-to-use-regional-vs-global-tables.html)
+- [`ALTER DATABASE ... SURVIVE {ZONE,REGION} FAILURE`](survive-failure.html)
+- [`ALTER TABLE ... SET LOCALITY ...`](set-locality.html)
 - [Topology Patterns Overview](topology-patterns.html)
-
-    - Single-region
-        - [Development](topology-development.html)
-        - [Basic Production](topology-basic-production.html)
-
-    - Multi-region
-        - [Geo-Partitioned Replicas](topology-geo-partitioned-replicas.html)
-        - [Geo-Partitioned Leaseholders](topology-geo-partitioned-leaseholders.html)
-        - [Duplicate Indexes](topology-duplicate-indexes.html)
-        - [Follow-the-Workload](topology-follow-the-workload.html)
+  - Single-region
+      - [Development](topology-development.html)
+      - [Basic Production](topology-basic-production.html)
+  - Multi-region
+      - [`REGIONAL` Table Locality Pattern](regional-tables.html)
+      - [`GLOBAL` Table Locality Pattern](global-tables.html)
+      - [Follow-the-Workload](topology-follow-the-workload.html)