diff --git a/src/current/_data/redirects.yml b/src/current/_data/redirects.yml index 9b664212ea2..21693068033 100644 --- a/src/current/_data/redirects.yml +++ b/src/current/_data/redirects.yml @@ -1161,3 +1161,15 @@ - destination: cockroachcloud/byoc-azure-deployment.md sources: ['cockroachcloud/byoc-deployment.md'] + +- destination: multiregion-overview.md + sources: ['demo-low-latency-multi-region-deployment.md', 'migrate-to-multiregion-sql.md'] + versions: ['v26.1', 'v26.2'] + +- destination: performance-best-practices-overview.md + sources: ['performance.md', 'performance-benchmarking-with-tpcc-local.md', 'performance-benchmarking-with-tpcc-small.md', 'performance-benchmarking-with-tpcc-medium.md', 'performance-benchmarking-with-tpcc-large.md', 'performance-benchmarking-with-tpcc-local-multiregion.md'] + versions: ['v26.1', 'v26.2'] + +- destination: support-resources.md + sources: ['file-an-issue.md'] + versions: ['v26.1', 'v26.2'] diff --git a/src/current/_includes/v26.1/filter-tabs/perf-bench-tpc-c.md b/src/current/_includes/v26.1/filter-tabs/perf-bench-tpc-c.md deleted file mode 100644 index 1394f916add..00000000000 --- a/src/current/_includes/v26.1/filter-tabs/perf-bench-tpc-c.md +++ /dev/null @@ -1,4 +0,0 @@ -{% assign tab_names_html = "Local;Local (Multi-Region);Small;Medium;Large" %} -{% assign html_page_filenames = "performance-benchmarking-with-tpcc-local.html;performance-benchmarking-with-tpcc-local-multiregion.html;performance-benchmarking-with-tpcc-small.html;performance-benchmarking-with-tpcc-medium.html;performance-benchmarking-with-tpcc-large.html" %} - -{% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder=page.version.version %} diff --git a/src/current/_includes/v26.1/misc/explore-benefits-see-also.md b/src/current/_includes/v26.1/misc/explore-benefits-see-also.md index d0993508e8f..e37cb974104 100644 --- a/src/current/_includes/v26.1/misc/explore-benefits-see-also.md +++ b/src/current/_includes/v26.1/misc/explore-benefits-see-also.md @@ -1,4 +1,3 @@ - [Replication & Rebalancing]({% link {{ page.version.version }}/demo-replication-and-rebalancing.md %}) - [CockroachDB Resilience]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}) -- [Low Latency Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) \ No newline at end of file diff --git a/src/current/_includes/v26.1/prod-deployment/insecure-test-load-balancing.md b/src/current/_includes/v26.1/prod-deployment/insecure-test-load-balancing.md index 130e032cae0..86e0228b368 100644 --- a/src/current/_includes/v26.1/prod-deployment/insecure-test-load-balancing.md +++ b/src/current/_includes/v26.1/prod-deployment/insecure-test-load-balancing.md @@ -4,10 +4,6 @@ CockroachDB comes with a number of [built-in workloads]({% link {{ page.version. Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine. {{site.data.alerts.end}} -{{site.data.alerts.callout_success}} -For comprehensive guidance on benchmarking CockroachDB with TPC-C, see [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}). -{{site.data.alerts.end}} - 1. SSH to the machine where you want the run the sample TPC-C workload. This should be a machine that is not running a CockroachDB node. diff --git a/src/current/_includes/v26.1/prod-deployment/prod-see-also.md b/src/current/_includes/v26.1/prod-deployment/prod-see-also.md index 88d81e565c9..e73619dea7d 100644 --- a/src/current/_includes/v26.1/prod-deployment/prod-see-also.md +++ b/src/current/_includes/v26.1/prod-deployment/prod-see-also.md @@ -2,6 +2,5 @@ - [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) - [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %}) - [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}) -- [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) - [Performance Tuning]({% link {{ page.version.version }}/performance-best-practices-overview.md %}) - [Local Deployment]({% link {{ page.version.version }}/start-a-local-cluster.md %}) diff --git a/src/current/_includes/v26.1/prod-deployment/secure-test-load-balancing.md b/src/current/_includes/v26.1/prod-deployment/secure-test-load-balancing.md index 26d2cc17e2d..ec2b8e7185c 100644 --- a/src/current/_includes/v26.1/prod-deployment/secure-test-load-balancing.md +++ b/src/current/_includes/v26.1/prod-deployment/secure-test-load-balancing.md @@ -4,8 +4,6 @@ CockroachDB comes with a number of [built-in workloads]({% link {{ page.version. Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine. {{site.data.alerts.end}} -For comprehensive guidance on benchmarking CockroachDB with TPC-C, refer to [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}). - 1. SSH to the machine where you want to run the sample TPC-C workload. This should be a machine that is not running a CockroachDB node, and it should already have a `certs` directory containing `ca.crt`, `client.root.crt`, and `client.root.key` files. diff --git a/src/current/_includes/v26.1/sidebar-data/multi-region-capabilities.json b/src/current/_includes/v26.1/sidebar-data/multi-region-capabilities.json index 4c07ee31a47..ab430da4596 100644 --- a/src/current/_includes/v26.1/sidebar-data/multi-region-capabilities.json +++ b/src/current/_includes/v26.1/sidebar-data/multi-region-capabilities.json @@ -28,6 +28,12 @@ "urls": [ "/${VERSION}/partitioning.html" ] + }, + { + "title": "Data Domiciling with CockroachDB Tutorial", + "urls": [ + "/${VERSION}/data-domiciling.html" + ] } ] }, @@ -42,29 +48,6 @@ "urls": [ "/${VERSION}/zone-config-extensions.html" ] - }, - { - "title": "Multi-Region Tutorials", - "items": [ - { - "title": "Low Latency Reads and Writes", - "urls": [ - "/${VERSION}/demo-low-latency-multi-region-deployment.html" - ] - }, - { - "title": "Data Domiciling with CockroachDB", - "urls": [ - "/${VERSION}/data-domiciling.html" - ] - }, - { - "title": "Migrate to Multi-Region SQL with Replication Zones", - "urls": [ - "/${VERSION}/migrate-to-multiregion-sql.html" - ] - } - ] } ] } diff --git a/src/current/_includes/v26.1/sidebar-data/reads-and-writes.json b/src/current/_includes/v26.1/sidebar-data/reads-and-writes.json index 36c99c45caf..e7b1dce4115 100644 --- a/src/current/_includes/v26.1/sidebar-data/reads-and-writes.json +++ b/src/current/_includes/v26.1/sidebar-data/reads-and-writes.json @@ -113,13 +113,6 @@ "/${VERSION}/local-testing.html" ] }, - { - "title": "SQL Playground", - "is_top_level": true, - "urls": [ - "https://www.cockroachlabs.com/docs/tutorials/sql-playground" - ] - }, { "title": "Database Management Tools", "items": [ diff --git a/src/current/_includes/v26.1/sidebar-data/troubleshooting.json b/src/current/_includes/v26.1/sidebar-data/troubleshooting.json index f9e11c5ab36..7a2103c9f62 100644 --- a/src/current/_includes/v26.1/sidebar-data/troubleshooting.json +++ b/src/current/_includes/v26.1/sidebar-data/troubleshooting.json @@ -74,39 +74,12 @@ "/${VERSION}/troubleshoot-replication-zones.html" ] }, - { - "title": "Benchmarking", - "items": [ - { - "title": "Overview", - "urls": [ - "/${VERSION}/performance.html" - ] - }, - { - "title": "Benchmarking with TPC-C", - "urls": [ - "/${VERSION}/performance-benchmarking-with-tpcc-local.html", - "/${VERSION}/performance-benchmarking-with-tpcc-local-multiregion.html", - "/${VERSION}/performance-benchmarking-with-tpcc-small.html", - "/${VERSION}/performance-benchmarking-with-tpcc-medium.html", - "/${VERSION}/performance-benchmarking-with-tpcc-large.html" - ] - } - ] - }, { "title": "Support Resources", "urls": [ "/${VERSION}/support-resources.html" ] }, - { - "title": "File an Issue", - "urls": [ - "/${VERSION}/file-an-issue.html" - ] - }, { "title": "Automatic CPU Profiler", "urls": [ diff --git a/src/current/_includes/v26.1/topology-patterns/see-also.md b/src/current/_includes/v26.1/topology-patterns/see-also.md index 87679440be3..bd93861affc 100644 --- a/src/current/_includes/v26.1/topology-patterns/see-also.md +++ b/src/current/_includes/v26.1/topology-patterns/see-also.md @@ -2,8 +2,6 @@ - [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) - [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`ALTER DATABASE ... SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`ALTER DATABASE ... DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/_includes/v26.1/zone-configs/remove-a-replication-zone.md b/src/current/_includes/v26.1/zone-configs/remove-a-replication-zone.md index e4db312ace4..8eea6aecae5 100644 --- a/src/current/_includes/v26.1/zone-configs/remove-a-replication-zone.md +++ b/src/current/_includes/v26.1/zone-configs/remove-a-replication-zone.md @@ -1,7 +1,7 @@ {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the multi-region abstractions created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} diff --git a/src/current/_includes/v26.2/filter-tabs/perf-bench-tpc-c.md b/src/current/_includes/v26.2/filter-tabs/perf-bench-tpc-c.md deleted file mode 100644 index 1394f916add..00000000000 --- a/src/current/_includes/v26.2/filter-tabs/perf-bench-tpc-c.md +++ /dev/null @@ -1,4 +0,0 @@ -{% assign tab_names_html = "Local;Local (Multi-Region);Small;Medium;Large" %} -{% assign html_page_filenames = "performance-benchmarking-with-tpcc-local.html;performance-benchmarking-with-tpcc-local-multiregion.html;performance-benchmarking-with-tpcc-small.html;performance-benchmarking-with-tpcc-medium.html;performance-benchmarking-with-tpcc-large.html" %} - -{% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder=page.version.version %} diff --git a/src/current/_includes/v26.2/misc/explore-benefits-see-also.md b/src/current/_includes/v26.2/misc/explore-benefits-see-also.md index d0993508e8f..e37cb974104 100644 --- a/src/current/_includes/v26.2/misc/explore-benefits-see-also.md +++ b/src/current/_includes/v26.2/misc/explore-benefits-see-also.md @@ -1,4 +1,3 @@ - [Replication & Rebalancing]({% link {{ page.version.version }}/demo-replication-and-rebalancing.md %}) - [CockroachDB Resilience]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}) -- [Low Latency Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) \ No newline at end of file diff --git a/src/current/_includes/v26.2/prod-deployment/insecure-test-load-balancing.md b/src/current/_includes/v26.2/prod-deployment/insecure-test-load-balancing.md index 130e032cae0..86e0228b368 100644 --- a/src/current/_includes/v26.2/prod-deployment/insecure-test-load-balancing.md +++ b/src/current/_includes/v26.2/prod-deployment/insecure-test-load-balancing.md @@ -4,10 +4,6 @@ CockroachDB comes with a number of [built-in workloads]({% link {{ page.version. Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine. {{site.data.alerts.end}} -{{site.data.alerts.callout_success}} -For comprehensive guidance on benchmarking CockroachDB with TPC-C, see [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}). -{{site.data.alerts.end}} - 1. SSH to the machine where you want the run the sample TPC-C workload. This should be a machine that is not running a CockroachDB node. diff --git a/src/current/_includes/v26.2/prod-deployment/prod-see-also.md b/src/current/_includes/v26.2/prod-deployment/prod-see-also.md index 88d81e565c9..e73619dea7d 100644 --- a/src/current/_includes/v26.2/prod-deployment/prod-see-also.md +++ b/src/current/_includes/v26.2/prod-deployment/prod-see-also.md @@ -2,6 +2,5 @@ - [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) - [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %}) - [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}) -- [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) - [Performance Tuning]({% link {{ page.version.version }}/performance-best-practices-overview.md %}) - [Local Deployment]({% link {{ page.version.version }}/start-a-local-cluster.md %}) diff --git a/src/current/_includes/v26.2/prod-deployment/secure-test-load-balancing.md b/src/current/_includes/v26.2/prod-deployment/secure-test-load-balancing.md index 26d2cc17e2d..ec2b8e7185c 100644 --- a/src/current/_includes/v26.2/prod-deployment/secure-test-load-balancing.md +++ b/src/current/_includes/v26.2/prod-deployment/secure-test-load-balancing.md @@ -4,8 +4,6 @@ CockroachDB comes with a number of [built-in workloads]({% link {{ page.version. Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine. {{site.data.alerts.end}} -For comprehensive guidance on benchmarking CockroachDB with TPC-C, refer to [Performance Benchmarking]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}). - 1. SSH to the machine where you want to run the sample TPC-C workload. This should be a machine that is not running a CockroachDB node, and it should already have a `certs` directory containing `ca.crt`, `client.root.crt`, and `client.root.key` files. diff --git a/src/current/_includes/v26.2/sidebar-data/multi-region-capabilities.json b/src/current/_includes/v26.2/sidebar-data/multi-region-capabilities.json index 4c07ee31a47..ab430da4596 100644 --- a/src/current/_includes/v26.2/sidebar-data/multi-region-capabilities.json +++ b/src/current/_includes/v26.2/sidebar-data/multi-region-capabilities.json @@ -28,6 +28,12 @@ "urls": [ "/${VERSION}/partitioning.html" ] + }, + { + "title": "Data Domiciling with CockroachDB Tutorial", + "urls": [ + "/${VERSION}/data-domiciling.html" + ] } ] }, @@ -42,29 +48,6 @@ "urls": [ "/${VERSION}/zone-config-extensions.html" ] - }, - { - "title": "Multi-Region Tutorials", - "items": [ - { - "title": "Low Latency Reads and Writes", - "urls": [ - "/${VERSION}/demo-low-latency-multi-region-deployment.html" - ] - }, - { - "title": "Data Domiciling with CockroachDB", - "urls": [ - "/${VERSION}/data-domiciling.html" - ] - }, - { - "title": "Migrate to Multi-Region SQL with Replication Zones", - "urls": [ - "/${VERSION}/migrate-to-multiregion-sql.html" - ] - } - ] } ] } diff --git a/src/current/_includes/v26.2/sidebar-data/reads-and-writes.json b/src/current/_includes/v26.2/sidebar-data/reads-and-writes.json index 36c99c45caf..e7b1dce4115 100644 --- a/src/current/_includes/v26.2/sidebar-data/reads-and-writes.json +++ b/src/current/_includes/v26.2/sidebar-data/reads-and-writes.json @@ -113,13 +113,6 @@ "/${VERSION}/local-testing.html" ] }, - { - "title": "SQL Playground", - "is_top_level": true, - "urls": [ - "https://www.cockroachlabs.com/docs/tutorials/sql-playground" - ] - }, { "title": "Database Management Tools", "items": [ diff --git a/src/current/_includes/v26.2/sidebar-data/troubleshooting.json b/src/current/_includes/v26.2/sidebar-data/troubleshooting.json index e20972a2b30..86a8a5296fc 100644 --- a/src/current/_includes/v26.2/sidebar-data/troubleshooting.json +++ b/src/current/_includes/v26.2/sidebar-data/troubleshooting.json @@ -80,39 +80,12 @@ "/${VERSION}/troubleshoot-replication-zones.html" ] }, - { - "title": "Benchmarking", - "items": [ - { - "title": "Overview", - "urls": [ - "/${VERSION}/performance.html" - ] - }, - { - "title": "Benchmarking with TPC-C", - "urls": [ - "/${VERSION}/performance-benchmarking-with-tpcc-local.html", - "/${VERSION}/performance-benchmarking-with-tpcc-local-multiregion.html", - "/${VERSION}/performance-benchmarking-with-tpcc-small.html", - "/${VERSION}/performance-benchmarking-with-tpcc-medium.html", - "/${VERSION}/performance-benchmarking-with-tpcc-large.html" - ] - } - ] - }, { "title": "Support Resources", "urls": [ "/${VERSION}/support-resources.html" ] }, - { - "title": "File an Issue", - "urls": [ - "/${VERSION}/file-an-issue.html" - ] - }, { "title": "Automatic CPU Profiler", "urls": [ diff --git a/src/current/_includes/v26.2/topology-patterns/see-also.md b/src/current/_includes/v26.2/topology-patterns/see-also.md index 87679440be3..bd93861affc 100644 --- a/src/current/_includes/v26.2/topology-patterns/see-also.md +++ b/src/current/_includes/v26.2/topology-patterns/see-also.md @@ -2,8 +2,6 @@ - [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) - [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`ALTER DATABASE ... SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`ALTER DATABASE ... DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/_includes/v26.2/zone-configs/remove-a-replication-zone.md b/src/current/_includes/v26.2/zone-configs/remove-a-replication-zone.md index e4db312ace4..8eea6aecae5 100644 --- a/src/current/_includes/v26.2/zone-configs/remove-a-replication-zone.md +++ b/src/current/_includes/v26.2/zone-configs/remove-a-replication-zone.md @@ -1,7 +1,7 @@ {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the multi-region abstractions created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} diff --git a/src/current/v26.1/alter-database.md b/src/current/v26.1/alter-database.md index 278a88479b0..3b42506e17a 100644 --- a/src/current/v26.1/alter-database.md +++ b/src/current/v26.1/alter-database.md @@ -729,7 +729,7 @@ ALTER DATABASE movr CONFIGURE ZONE USING range_min_bytes = 0, range_max_bytes = {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region] ({% link {{ page.version.version }}/multiregion-overview.md %}) created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} @@ -1202,7 +1202,7 @@ To follow along with the examples below: cockroach demo --global --nodes 9 ~~~ -1. Set the demo cluster's [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) as described in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) (specifically, starting at [Step 5. Execute multi-region SQL statements]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#step-5-execute-multi-region-sql-statements)). +1. Set the demo cluster's [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality). 1. Enable the replica placement syntax with either the [session variable]({% link {{ page.version.version }}/set-vars.md %}) or the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) as shown below. diff --git a/src/current/v26.1/alter-index.md b/src/current/v26.1/alter-index.md index 6b686f7fd0d..978b65451f7 100644 --- a/src/current/v26.1/alter-index.md +++ b/src/current/v26.1/alter-index.md @@ -243,7 +243,7 @@ ALTER INDEX vehicles@vehicles_auto_index_fk_city_ref_users CONFIGURE ZONE USING {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region] ({% link {{ page.version.version }}/multiregion-overview.md %}) created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} diff --git a/src/current/v26.1/alter-table.md b/src/current/v26.1/alter-table.md index 3001ee1834e..ea5189368cb 100644 --- a/src/current/v26.1/alter-table.md +++ b/src/current/v26.1/alter-table.md @@ -1293,7 +1293,7 @@ Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %} {% include {{page.version.version}}/sql/indexes-regional-by-row.md %} -This example assumes you have a simulated multi-region database running on your local machine following the steps described in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). It shows how a `UNIQUE` index is partitioned, but it's similar to how all indexes are partitioned on `REGIONAL BY ROW` tables. +This example assumes you have a simulated multi-region database running on your local machine. It shows how a `UNIQUE` index is partitioned, but it's similar to how all indexes are partitioned on `REGIONAL BY ROW` tables. To show how the automatic partitioning of indexes on `REGIONAL BY ROW` tables works, we will: @@ -1313,7 +1313,7 @@ ALTER TABLE users ADD COLUMN email STRING; ALTER TABLE users ADD CONSTRAINT user_email_unique UNIQUE (email); ~~~ -Next, issue the [`SHOW INDEXES`]({% link {{ page.version.version }}/show-index.md %}) statement. You will see that [the implicit region column](#set-the-table-locality-to-regional-by-row) that was added when the table [was converted to regional by row]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#configure-regional-by-row-tables) is now indexed: +Next, issue the [`SHOW INDEXES`]({% link {{ page.version.version }}/show-index.md %}) statement. You will see that [the implicit region column](#set-the-table-locality-to-regional-by-row) that was added when the table was converted to regional by row is now indexed: {% include_cached copy-clipboard.html %} ~~~ sql @@ -1664,7 +1664,7 @@ If the column has the [`NOT NULL` constraint]({% link {{ page.version.version }} #### Convert to a different data type -The [TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) database has a `customer` table with a column `c_credit_lim` of type `DECIMAL(10,2)`: +The TPC-C database has a `customer` table with a column `c_credit_lim` of type `DECIMAL(10,2)`: {% include_cached copy-clipboard.html %} ~~~ sql @@ -1704,7 +1704,7 @@ To change the data type from `DECIMAL` to `STRING`: #### Change a column type's precision -The [TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) `customer` table contains a column `c_balance` of type `DECIMAL(12,2)`: +The TPC-C `customer` table contains a column `c_balance` of type `DECIMAL(12,2)`: {% include_cached copy-clipboard.html %} ~~~ sql @@ -2860,7 +2860,7 @@ ALTER TABLE {table} ALTER COLUMN crdb_region SET ON UPDATE rehome_row()::db.publ ##### Example -1. Follow steps 1 and 2 from the [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) tutorial. This will involve starting a [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) cluster in a terminal window (call it _terminal 1_). +1. Start a [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) cluster in a terminal window (call it _terminal 1_). 1. From the [SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) running in terminal 1, set the setting that enables auto-rehoming. You must issue this setting before creating the `REGIONAL BY ROW` tables that you want auto-rehomed. @@ -2869,7 +2869,7 @@ ALTER TABLE {table} ALTER COLUMN crdb_region SET ON UPDATE rehome_row()::db.publ SET enable_auto_rehoming = on; ~~~ -1. In a second terminal window (call it _terminal 2_), [finish the tutorial starting from step 3]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#step-3-load-and-run-movr) onward to finish loading the cluster with data and applying the multi-region SQL configuration. +1. In a second terminal window (call it _terminal 2_), finish loading the cluster with data and applying the multi-region SQL configuration. 1. Switch back to terminal 1, and check the gateway region of the node you are currently connected to: diff --git a/src/current/v26.1/choosing-a-multi-region-configuration.md b/src/current/v26.1/choosing-a-multi-region-configuration.md index d31479987dc..1b48d1519fb 100644 --- a/src/current/v26.1/choosing-a-multi-region-configuration.md +++ b/src/current/v26.1/choosing-a-multi-region-configuration.md @@ -65,7 +65,6 @@ Different databases and tables within the same cluster can each use different co - [Survive Region Outages with CockroachDB](https://www.cockroachlabs.com/blog/under-the-hood-multi-region/) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.1/cluster-setup-troubleshooting.md b/src/current/v26.1/cluster-setup-troubleshooting.md index e7c16577c14..d952f1af609 100644 --- a/src/current/v26.1/cluster-setup-troubleshooting.md +++ b/src/current/v26.1/cluster-setup-troubleshooting.md @@ -91,7 +91,7 @@ You should see a list of the built-in databases: If you’re not seeing the output above, check for the following: - `connection refused` error, which indicates you have not included some flag that you used to start the node. We have additional troubleshooting steps for this error [here]({% link {{ page.version.version }}/common-errors.md %}#connection-refused). -- The node crashed. To ascertain if the node crashed, run `ps | grep cockroach` to look for the `cockroach` process. If you cannot locate the `cockroach` process (i.e., it crashed), [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}), including the [logs from your node]({% link {{ page.version.version }}/configure-logs.md %}#logging-directory) and any errors you received. +- The node crashed. To ascertain if the node crashed, run `ps | grep cockroach` to look for the `cockroach` process. If you cannot locate the `cockroach` process (i.e., it crashed), file an issue in Github, including the [logs from your node]({% link {{ page.version.version }}/configure-logs.md %}#logging-directory) and any errors you received. ## Cannot run a multi-node CockroachDB cluster on the same machine @@ -526,7 +526,7 @@ CockroachDB memory usage has the following components: {% include {{ page.version.version }}/prod-deployment/healthy-crdb-memory.md %} - If you observe values not within the expected range for a healthy cluster, [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). + If you observe values not within the expected range for a healthy cluster, file an issue in Github. #### Out-of-memory (OOM) crash @@ -582,7 +582,7 @@ To identify under-replicated/unavailable ranges: 1. On the [**Cluster Overview** page]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}), check the **Replication Status**. If the **Under-replicated ranges** or **Unavailable ranges** count is non-zero, then you have under-replicated or unavailable ranges in your cluster. -1. Check for a network partition: On the [**Network** page]({% link {{ page.version.version }}/ui-network-latency-page.md %}), if there are nodes in the network matrix with [no connections]({% link {{ page.version.version }}/ui-network-latency-page.md %}#no-connections), this may indicate a network partition. If there is no partition and still no upreplication after 5 minutes, then [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). +1. Check for a network partition: On the [**Network** page]({% link {{ page.version.version }}/ui-network-latency-page.md %}), if there are nodes in the network matrix with [no connections]({% link {{ page.version.version }}/ui-network-latency-page.md %}#no-connections), this may indicate a network partition. If there is no partition and still no upreplication after 5 minutes, then file an issue in Github. **Add nodes to the cluster:** @@ -594,7 +594,7 @@ If you still see under-replicated/unavailable ranges on the Cluster Overview pag 1. On the [**Advanced Debug** page]({% link {{ page.version.version }}/ui-debug-pages.md %}), click **Problem Ranges**. 1. In the **Connections** table, identify the node with the under-replicated/unavailable ranges and click the node ID in the Node column. 1. To view the **Range Report** for a range, click on the range number in the **Under-replicated (or slow)** table or **Unavailable** table. -1. On the Range Report page, scroll down to the **Simulated Allocator Output** section. The table contains an error message which explains the reason for the under-replicated range. Follow the guidance in the message to resolve the issue. If you need help understanding the error or the guidance, [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). Please be sure to include the full Range Report and error message when you submit the issue. +1. On the Range Report page, scroll down to the **Simulated Allocator Output** section. The table contains an error message which explains the reason for the under-replicated range. Follow the guidance in the message to resolve the issue. If you need help understanding the error or the guidance, file an issue in Github. Please be sure to include the full Range Report and error message when you submit the issue. #### Check for under-replicated or unavailable data diff --git a/src/current/v26.1/cockroach-debug-encryption-active-key.md b/src/current/v26.1/cockroach-debug-encryption-active-key.md index 7c1ddf7988e..80f43344ed9 100644 --- a/src/current/v26.1/cockroach-debug-encryption-active-key.md +++ b/src/current/v26.1/cockroach-debug-encryption-active-key.md @@ -40,6 +40,5 @@ AES128_CTR:be235c29239aa84a48e5e1874d76aebf7fb3c1bdc438cec2eb98de82f06a57a0 ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.1/cockroach-debug-encryption-decrypt.md b/src/current/v26.1/cockroach-debug-encryption-decrypt.md index 94b88d85ba0..10b10c90ec2 100644 --- a/src/current/v26.1/cockroach-debug-encryption-decrypt.md +++ b/src/current/v26.1/cockroach-debug-encryption-decrypt.md @@ -57,7 +57,6 @@ The `cockroach debug encryption-decrypt` command will output the decrypted store ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) diff --git a/src/current/v26.1/cockroach-debug-job-trace.md b/src/current/v26.1/cockroach-debug-job-trace.md index 0684f385172..eb0047826b6 100644 --- a/src/current/v26.1/cockroach-debug-job-trace.md +++ b/src/current/v26.1/cockroach-debug-job-trace.md @@ -70,7 +70,6 @@ You will find the zip file in the directory you ran the command from: ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) diff --git a/src/current/v26.1/cockroach-debug-merge-logs.md b/src/current/v26.1/cockroach-debug-merge-logs.md index 4ebed81dd51..8dd6c4ecd23 100644 --- a/src/current/v26.1/cockroach-debug-merge-logs.md +++ b/src/current/v26.1/cockroach-debug-merge-logs.md @@ -84,6 +84,5 @@ As of v23.2, logs can be configured to use a [timezone with formats `crdb-v1` or ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.1/cockroach-debug-tsdump.md b/src/current/v26.1/cockroach-debug-tsdump.md index 36611b61109..4a96b75a0a4 100644 --- a/src/current/v26.1/cockroach-debug-tsdump.md +++ b/src/current/v26.1/cockroach-debug-tsdump.md @@ -184,6 +184,5 @@ $ cockroach debug tsdump --format=raw --metrics-list-file=metrics.txt --certs-di ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.1/cockroach-debug-zip.md b/src/current/v26.1/cockroach-debug-zip.md index fb1ebef87c3..9a387069d48 100644 --- a/src/current/v26.1/cockroach-debug-zip.md +++ b/src/current/v26.1/cockroach-debug-zip.md @@ -285,6 +285,5 @@ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host=2 ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.1/cockroach-demo.md b/src/current/v26.1/cockroach-demo.md index 029d2f0c252..47257c7f236 100644 --- a/src/current/v26.1/cockroach-demo.md +++ b/src/current/v26.1/cockroach-demo.md @@ -489,8 +489,6 @@ This command starts a 9-node demo cluster with the `movr` database preloaded and The `--global` flag is an experimental feature of `cockroach demo`. The interface and output are subject to change. {{site.data.alerts.end}} -For a tutorial that uses a demo cluster to demonstrate CockroachDB's multi-region capabilities, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ### Add, shut down, and restart nodes in a multi-node demo cluster In a multi-node demo cluster, you can use `\demo` [shell commands](#commands) to add, shut down, restart, decommission, and recommission individual nodes. diff --git a/src/current/v26.1/cockroach-start.md b/src/current/v26.1/cockroach-start.md index 831f0a9e449..89e6e23c4c0 100644 --- a/src/current/v26.1/cockroach-start.md +++ b/src/current/v26.1/cockroach-start.md @@ -449,7 +449,7 @@ $ cockroach init \ ### Start a multi-region cluster -In this example we will start a multi-node [local cluster]({% link {{ page.version.version }}/start-a-local-cluster.md %}) with a multi-region setup that uses the same regions (passed to the [`--locality`](#locality) flag) as the [multi-region MovR demo application]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +In this example we will start a multi-node [local cluster]({% link {{ page.version.version }}/start-a-local-cluster.md %}) with a multi-region setup that uses the same regions (passed to the [`--locality`](#locality) flag) as the multi-region MovR demo application. 1. Start a node in the `us-east1` region: @@ -518,8 +518,6 @@ In this example we will start a multi-node [local cluster]({% link {{ page.versi For more information about running CockroachDB multi-region, see the [Multi-region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). -For a more advanced example showing how to run a simulated workload on a multi-region CockroachDB cluster on your local machine, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - {{site.data.alerts.callout_info}} For more information about the `--locality` flag, see [Locality](#locality). {{site.data.alerts.end}} diff --git a/src/current/v26.1/cockroach-workload.md b/src/current/v26.1/cockroach-workload.md index 439d4b7f423..6ad72918b82 100644 --- a/src/current/v26.1/cockroach-workload.md +++ b/src/current/v26.1/cockroach-workload.md @@ -674,4 +674,3 @@ To customize the frequency of per-operation statistics, use the `--display-every - [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) -- [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) diff --git a/src/current/v26.1/data-domiciling.md b/src/current/v26.1/data-domiciling.md index fa3af83438e..2c9c66e013e 100644 --- a/src/current/v26.1/data-domiciling.md +++ b/src/current/v26.1/data-domiciling.md @@ -138,7 +138,7 @@ ALTER DATABASE movr ADD REGION "us-west1"; Next, check the [critical nodes status endpoint](monitoring-and-alerting.html#critical-nodes-endpoint) to see which ranges are still not in compliance with your desired domiciling: that data on EU-based entities (users, etc.) does not leave EU-based nodes. -On a small demo cluster like this one, the data movement from the previous step should finish quickly; on larger clusters, the rebalancing process may take longer. For more information about the performance considerations of rebalancing data in multi-region clusters, see [Performance considerations](migrate-to-multiregion-sql.html#performance-considerations). +On a small demo cluster like this one, the data movement from the previous step should finish quickly; on larger clusters, the rebalancing process may take longer. With the default settings, you should expect some replicas in the cluster to be violating this constraint. Those replicas will appear in the `violatingConstraints` field of the output. @@ -436,9 +436,7 @@ Using CockroachDB as part of your approach to data domiciling has several limita ## See also - [How to Choose a Multi-region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Multi-Region Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) - [Reads and Writes in CockroachDB]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}) - [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) diff --git a/src/current/v26.1/demo-low-latency-multi-region-deployment.md b/src/current/v26.1/demo-low-latency-multi-region-deployment.md deleted file mode 100644 index a94b48923ff..00000000000 --- a/src/current/v26.1/demo-low-latency-multi-region-deployment.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Low Latency Reads and Writes in a Multi-Region Cluster -summary: Use data topologies to get low-latency reads and writes in a multi-region CockroachDB cluster. -toc: true -toc_not_nested: true -key: demo-geo-partitioning.html -docs_area: ---- - -CockroachDB multi-region capabilities make it easier to run global applications. For an overview of these capabilities, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -In multi-region clusters, the distribution of data becomes a performance consideration. This makes it important to think about the [survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) of each database. Then, for each table in the database, use the right [table locality]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) to locate data for optimal performance. - -In this tutorial, you will: - -1. Simulate a multi-region CockroachDB cluster on your local machine. -1. Run a workload on the cluster using our fictional vehicle-sharing application called [MovR]({% link {{ page.version.version }}/movr.md %}). -1. See the effects of network latency on SQL query performance in the default (non-multi-region) configuration. -1. Configure the cluster for good multi-region performance by issuing SQL statements that choose the right [survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality). - -## Considerations - -This page describes a demo cluster; it does not show best practices for a production deployment. For more information about production deployments of multi-region applications, see [Orchestrate CockroachDB Across Multiple Kubernetes Clusters]({% link {{ page.version.version }}/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md %}) and the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). - -Because the instructions on this page describe how to simulate a multi-region cluster on a single machine, the absolute performance numbers described below are not reflective of [the performance you can expect of single-point reads and writes against CockroachDB in a production setting]({% link {{ page.version.version }}/frequently-asked-questions.md %}#single-row-perf). Instead, the instructions are designed with the following goals: - -- To show the _relative_ magnitude of the performance improvements to expect when you configure a multi-region cluster correctly. -- To be as easy to try as possible with minimal configuration and setup. - -## Before you begin - -Make sure you have: - -- [A basic understanding of the MovR application](#a-basic-understanding-of-the-movr-application) -- [Docker](https://www.docker.com) installed on the local machine - -### A basic understanding of the MovR application - -The workload you'll run against the cluster is our open-source, fictional, peer-to-peer vehicle-sharing app, [MovR]({% link {{ page.version.version }}/movr.md %}). Each instance represents users in a specific region: - -- `europe-west1`, covering the cities of Amsterdam, Paris, and Rome. -- `us-east1`, covering the cities of New York, Boston, and Washington, D.C. -- `us-west1`, covering the cities of Los Angeles, San Francisco, and Seattle. - -#### The MovR schema - -{% include {{ page.version.version }}/misc/movr-schema.md %} - -All of the tables except `promo_codes` have a composite primary key of `city` and `id`, in that order. This means that the rows in these tables are ordered by their geography. These tables are read from and written to very frequently. To keep read and write latency low, you'll use the [`REGIONAL BY ROW` table locality pattern]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) for these tables. - -The data in the `promo_codes` table is different: it is not tied to geography, and it is rarely updated. This type of table is often referred to as a "reference table" or "lookup table". In this case, you'll use the [Global table locality pattern]({% link {{ page.version.version }}/table-localities.md %}#global-tables) to keep read latencies low. - -For a description of the sequence of SQL statements issued by the MovR application in response to user actions, see [How the MovR application works]({% link {{ page.version.version }}/movr.md %}#how-the-movr-application-works). - -## Step 1. Simulate a multi-region cluster - -{% include {{page.version.version}}/sql/start-a-multi-region-demo-cluster.md %} - -To verify that the simulated latencies are working as expected, check the [Network Latency Page]({% link {{ page.version.version }}/ui-network-latency-page.md %}) in the DB Console. Round trip times between `us-west1` and `europe-west1` should be in the 150 ms range. - -## Step 2. Determine node locations - -To determine which nodes are in which regions, you will need to refer to two (2) things: - -1. The output of the `\demo ls` from the SQL shell, which shows the TCP ports on the local machine that we will connect to from the MovR application. -1. The node IDs shown on the **Network Latency Page**. - -Here is the output of `\demo ls` from the SQL shell. - -{% include_cached copy-clipboard.html %} -~~~ -> \demo ls -~~~ - -~~~ -node 1: - (webui) http://127.0.0.1:8080/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26257?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257 - -node 2: - (webui) http://127.0.0.1:8081/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26258?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26258 - -node 3: - (webui) http://127.0.0.1:8082/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26259?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26259 - -node 4: - (webui) http://127.0.0.1:8083/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26260?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26260 - -node 5: - (webui) http://127.0.0.1:8084/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26261?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26261 - -node 6: - (webui) http://127.0.0.1:8085/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26262?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26262 - -node 7: - (webui) http://127.0.0.1:8086/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26263?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26263 - -node 8: - (webui) http://127.0.0.1:8087/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26264?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26264 - -node 9: - (webui) http://127.0.0.1:8088/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26265?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26265 -~~~ - -And here is the view on the **Network Latency Page**, which shows which nodes are in which cluster regions: - -Geo-partitioning network latency - -You can see by referring back and forth between `\demo ls` and the **Network Latency Page** that the cluster has the following region/node/port correspondences, which we can use to determine how to connect MovR from various regions: - -| Node ID | Region | Port on localhost | -|---------+--------------+-------------------| -| N2 | europe-west1 | 26263 | -| N5 | europe-west1 | 26264 | -| N7 | europe-west1 | 26265 | -| N4 | us-west1 | 26262 | -| N6 | us-west1 | 26260 | -| N9 | us-west1 | 26261 | -| N1 | us-east1 | 26257 | -| N3 | us-east1 | 26259 | -| N8 | us-east1 | 26258 | - -## Step 3. Load and run MovR - -Follow these steps to start 3 instances of MovR. Each instance is pointed at a node in a different region. This will simulate load from that region. - -1. In the SQL shell, create the `movr` database: - - {% include_cached copy-clipboard.html %} - ~~~ sql - CREATE DATABASE IF NOT EXISTS movr; - ~~~ - -1. Open a second terminal and run the command below to populate the MovR data set. The options are mostly self-explanatory. We limit the application to 1 thread because using multiple threads quickly overloads this small demo cluster's ability to ingest data. As a result, loading the data takes about 90 seconds on a fast laptop. - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-load" \ - --url "postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable" \ - --num-threads 1 \ - load \ - --num-users 100 \ - --num-rides 100 \ - --num-vehicles 10 \ - --city "boston" \ - --city "new york" \ - --city "washington dc" \ - --city="amsterdam" \ - --city="paris" \ - --city="rome" \ - --city="los angeles" \ - --city="san francisco" \ - --city="seattle" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable - [INFO] (MainThread) Loading single region MovR - [INFO] (MainThread) initializing tables - [INFO] (MainThread) loading cities ['boston', 'new york', 'washington dc', 'amsterdam', 'paris', 'rome', 'los angeles', 'san francisco', 'seattle'] - [INFO] (MainThread) loading movr data with ~100 users, ~10 vehicles, ~100 rides, ~1000 histories, and ~1000 promo codes - [INFO] (Thread-1 ) Generating user data for boston... - ... output snipped ... - [INFO] (Thread-1 ) Generating 1000 promo codes... - [INFO] (MainThread) populated 9 cities in 86.986230 seconds - ~~~ - -1. In the same terminal window, run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-us-east" \ - --url "postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable" \ - run \ - --city="boston" \ - --city="new york" \ - --city="washington dc" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['boston', 'new york', 'washington dc'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ... - ~~~ - -1. Open a third terminal and run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-us-west" \ - --url "postgres://root@docker.for.mac.localhost:26260/movr?sslmode=disable" \ - run \ - --city="los angeles" \ - --city="san francisco" \ - --city="seattle" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26260/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['los angeles', 'san francisco', 'seattle'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ~~~ - -1. Open a fourth terminal and run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-eu-west" \ - --url "postgres://root@docker.for.mac.localhost:26264/movr?sslmode=disable" \ - run \ - --city="amsterdam" \ - --city="paris" \ - --city="rome" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26264/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['amsterdam', 'paris', 'rome'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ... - ~~~ - -## Step 4. Check service latency - -Now that you have load hitting the cluster from different regions, check how the service latencies look before you do any multi-region configuration from SQL. This is the "before" case in the "before and after". - -In the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) at http://127.0.0.1:8080, click [**Metrics**]({% link {{ page.version.version }}/ui-overview-dashboard.md %}) on the left and hover over the [**Service Latency: SQL, 99th percentile**]({% link {{ page.version.version }}/ui-overview-dashboard.md %}#service-latency-sql-99th-percentile) timeseries graph. You should see the effects of network latency on this workload. - -Geo-partitioning SQL latency - -For each of the 3 nodes that you are pointing the movr workload at, the max latency of 99% of queries are in the 1-2 seconds range. The SQL latency is high because of the network latency between regions. - -To see the network latency between any two nodes in the cluster, click [**Network Latency**]({% link {{ page.version.version }}/ui-network-latency-page.md %}) in the left-hand navigation. - -Geo-partitioning network latency - -Within a single region, round-trip latency is under 6 ms (milliseconds). Across regions, round-trip latency is significantly higher. - -For example: - -- Round-trip latency between **N2** in `europe-west1` and **N3** in `us-east1` is 87 ms. -- Round-trip latency between **N2** in `europe-west1` and **N4** in `us-west1` is 196 ms. - -## Step 5. Execute multi-region SQL statements - -The following SQL statements will configure: - -- [The database's available regions](#configure-database-regions). -- [Which data should be optimized for access from which region](#configure-table-localities). - -This information is necessary so that CockroachDB can move data around to optimize access to particular data from particular regions. The main focus is reducing latency in a global deployment. For more information about how this works at a high level, see the [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -{{site.data.alerts.callout_info}} -The following `ALTER` statements will take some seconds to run, since the cluster is under load. -{{site.data.alerts.end}} - -### Configure database regions - -Back in the SQL shell, switch to the `movr` database: - -{% include_cached copy-clipboard.html %} -~~~ sql -USE movr; -~~~ - -{% include {{page.version.version}}/sql/multiregion-movr-add-regions.md %} - -### Configure table localities - -#### Configure GLOBAL tables - -As mentioned earlier, all of the tables except `promo_codes` are geographically specific. - -{% include {{page.version.version}}/sql/multiregion-movr-global.md %} - -#### Configure REGIONAL BY ROW tables - -{% include {{page.version.version}}/sql/multiregion-movr-regional-by-row.md %} - -## Step 6. Re-check service latency - -As the multi-region schema changes complete, you should see changes to the following metrics: - -- **SQL Queries**: This number should go up, since the cluster can service more load due to better performance (due to better data locality and lower latency). In this particular run, **the QPS has almost doubled, from 87 to 164**. -- **Service Latency: SQL, 99th percentile**: In general, even on a small demo cluster like this, the P99 latency should drop and also get less spiky over time, as schema changes finish and data is moved around. For this particular run, **the P99 latency has dropped from ~1200 ms to ~870 ms, an over 25% improvement**. -- **Replicas per Node**: This will increase, since the data needs to be spread across more nodes in order to service the multi-region workload appropriately. There is nothing you need to do about this, except to note that it happens, and is required for CockroachDB's improved multi-region performance features to work. - -{{site.data.alerts.callout_info}} -The small demo cluster used in this example is essentially in a state of overload from the start. The performance numbers shown here only reflect the direction of the performance improvements. You should expect to see much better absolute performance numbers than those described here [in a production deployment]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -Geo-partitioning SQL latency - -## See also - -- [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) -- [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) -- [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) -- [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) -- [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) -- [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) -- [Reads and Writes in CockroachDB]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}) -- [Install CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}) diff --git a/src/current/v26.1/file-an-issue.md b/src/current/v26.1/file-an-issue.md deleted file mode 100644 index 9255e2c08b2..00000000000 --- a/src/current/v26.1/file-an-issue.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: File an Issue -summary: Learn how to file a GitHub issue with CockroachDB. -toc: false -docs_area: manage ---- - -If you've tried to [troubleshoot]({% link {{ page.version.version }}/troubleshooting-overview.md %}) an issue yourself, have [reached out for help]({% link {{ page.version.version }}/support-resources.md %}), and are still stumped, you can file an issue in GitHub. - -To file an issue in GitHub, we need the following information: - -1. A summary of the issue. - -1. The steps to reproduce the issue. - -1. The result you expected. - -1. The result that actually occurred. - -1. The first few lines of the log file from each node in the cluster in a timeframe as close as possible to reproducing the issue. On most Unix-based systems running with defaults, you can get this information using the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ grep -F '[config]' cockroach-data/logs/cockroach.log - ~~~ - {{site.data.alerts.callout_info}}You might need to replace cockroach-data/logs with the location of your logs.{{site.data.alerts.end}} - If the logs are not available, include the output of `cockroach version` for each node in the cluster. - -### Template - -You can use this as a template for [filing an issue in GitHub](https://github.com/cockroachdb/cockroach/issues/new): - -~~~ - -## Summary - - - -## Steps to reproduce - -1. -2. -3. - -## Expected Result - - - -## Actual Result - - - -## Log files/version - -### Node 1 - - - -### Node 2 - - - -### Node 3 - - - -~~~ diff --git a/src/current/v26.1/frequently-asked-questions.md b/src/current/v26.1/frequently-asked-questions.md index 2bac8e0ffe6..bc28ed89750 100644 --- a/src/current/v26.1/frequently-asked-questions.md +++ b/src/current/v26.1/frequently-asked-questions.md @@ -68,7 +68,7 @@ CockroachDB replicates your data for availability and guarantees consistency bet - Different servers on different racks within a datacenter to tolerate rack power/network failures - Different servers in different datacenters to tolerate large scale network or power outages -In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to locate data for optimal performance and resiliency. For a step-by-step demonstration, see [Low Latency Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to locate data for optimal performance and resiliency. **Automated Repair** diff --git a/src/current/v26.1/global-tables.md b/src/current/v26.1/global-tables.md index ffd7928a817..202309cf20c 100644 --- a/src/current/v26.1/global-tables.md +++ b/src/current/v26.1/global-tables.md @@ -61,7 +61,7 @@ To use this pattern, set the [table locality]({% link {{ page.version.version }} ~~~ {{site.data.alerts.callout_success}} -A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. For a tutorial showing how table localities can improve performance metrics across a multi-region cluster, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. {{site.data.alerts.end}} ## Characteristics @@ -96,10 +96,6 @@ The value of `kv.closed_timestamp.lead_for_global_reads_override` will impact wr - If rows in the table, and all latency-sensitive queries, can be tied to specific geographies, consider the [`REGIONAL` Table Locality Pattern]({% link {{ page.version.version }}/regional-tables.md %}) pattern. -## Tutorial - -For a step-by-step demonstration showing how CockroachDB's multi-region capabilities (including `GLOBAL` and `REGIONAL` tables) give you low-latency reads in a distributed cluster, see the tutorial on [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## See also {% include {{ page.version.version }}/topology-patterns/see-also.md %} diff --git a/src/current/v26.1/index.md b/src/current/v26.1/index.md index 5c612ce3c0d..ee5277a0a6a 100644 --- a/src/current/v26.1/index.md +++ b/src/current/v26.1/index.md @@ -79,7 +79,6 @@ docs_area:
  • Production Checklist
  • CockroachDB Cloud Deployment
  • Kubernetes Overview
    • -
  • Performance Profiles
  • Cluster Maintenance
    • diff --git a/src/current/v26.1/local-testing.md b/src/current/v26.1/local-testing.md index 871c4d77d11..f56c15a3fed 100644 --- a/src/current/v26.1/local-testing.md +++ b/src/current/v26.1/local-testing.md @@ -49,7 +49,7 @@ ALTER DATABASE system CONFIGURE ZONE USING "gc.ttlseconds" = 600; ~~~ {{site.data.alerts.callout_danger}} -These settings **are not** recommended for [performance benchmarking of CockroachDB]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}) since they will lead to inaccurate results. +These settings **are not** recommended for performance benchmarking of CockroachDB since they will lead to inaccurate results. {{site.data.alerts.end}} ## Scope tests to a database when possible diff --git a/src/current/v26.1/migrate-to-multiregion-sql.md b/src/current/v26.1/migrate-to-multiregion-sql.md deleted file mode 100644 index 54e665eefdb..00000000000 --- a/src/current/v26.1/migrate-to-multiregion-sql.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Migrate to Multi-Region SQL -summary: Learn how to migrate to CockroachDB multi-region SQL user features. -toc: true -docs_area: deploy ---- - -This page describes how to migrate a multi-region cluster from using replication zones to using multi-region SQL abstractions. - -## Overview - -{{site.data.alerts.callout_info}} -If you are already using [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) to control your multi-region cluster, you can ignore this page. -{{site.data.alerts.end}} - -CockroachDB v21.1 added support for [improved multi-region capabilities that make it easier to run global applications]({% link {{ page.version.version }}/multiregion-overview.md %}). Using high-level SQL statements, you can control where your data is stored and how it is accessed to provide good performance and tunable latency for your application's users. - -Prior to v21.1, the only way to accomplish these goals in a multi-region cluster involved using lower-level mechanisms called [replication zones]({% link {{ page.version.version }}/configure-replication-zones.md %}) in specific patterns called _Duplicate indexes_, _Geo-partitioned replicas_, and _Geo-partitioned leaseholders_. - -These patterns and the use of replication zones are still fully supported. However, for most users, they are harder to use and in some cases can result in worse performance than the multi-region SQL abstractions. - -This page discusses: - -- Mappings from each of the legacy replication-zone-based patterns to the 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 underlying zone configuration changes that result from running the multi-region SQL statements. - -## Replication zone patterns and multi-region SQL abstractions - -{% include {{page.version.version}}/sql/replication-zone-patterns-to-multiregion-sql-mapping.md %} - -{{site.data.alerts.callout_info}} -CockroachDB will no longer provide the [Follow-the-Workload]({% link {{ page.version.version }}/topology-follow-the-workload.md %}) pattern's behavior for a database if you use the [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) with that database. In other words, the multi-region SQL statements do not provide a behavior that is analogous to Follow-the-Workload. -{{site.data.alerts.end}} - -For more information about how to use `ZONE` vs. `REGION` survival goals, see [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -For more information about when to use `GLOBAL` vs. `REGIONAL` tables, see [When to `Use` `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables). - -## How to migrate a database to the multi-region SQL abstractions - -The following instructions assume that you will re-use your existing [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions) (that is, regions added during cluster setup using [`cockroach start --locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality)). - -### Performance considerations - -Expect performance to be temporarily affected by this process. When you run the commands described below, the cluster may need to do a significant amount of work to meet the new replica placement constraints it has just been given. Therefore, we recommend running this procedure at a time when you would normally perform scheduled maintenance. - -Depending on how long you are willing to wait between steps for the replica rebalancing process to settle down, data movement may still be occurring when the next set of constraints is added using the multi-region SQL abstractions; this may lead to further data movement. - -In other words, the process described here may result in a significant increase in CPU usage, IOPS, and network traffic while the cluster rebalances replicas to meet the final set of constraints you have provided it with. Until this process completes, the cluster may not be able to handle its normal workload. - -Note that the process of dropping the old zone configs that occurs when the old configurations are removed **must be complete** before you can [add regions to the database]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and set [table localities]({% link {{ page.version.version }}/alter-table.md %}#set-locality). You can ensure this process is complete by waiting for the [`ALTER DATABASE ... CONFIGURE ZONE DISCARD`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement shown below to finish successfully. - -For a tutorial that shows how to transition a database to using multi-region SQL statements, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - -{{site.data.alerts.callout_info}} -As part of this migration, data may move temporarily out of the geography where you have constrained it to be placed. For more information about CockroachDB's support for data domiciling, see [Data Domiciling with CockroachDB]({% link {{ page.version.version }}/data-domiciling.md %}). -{{site.data.alerts.end}} - -### Step 1. Remove the old replication zone configurations - -Depending on which [legacy multi-region topology pattern]({% link {{ page.version.version }}/topology-patterns.md %}#multi-region) you are migrating from, the procedure will vary. For instructions showing how to remove the existing zone configuration for each pattern, see below. - -- [Duplicate indexes](#duplicate-indexes) -- [Geo-partitioned leaseholders](#geo-partitioned-leaseholders) -- [Geo-partitioned replicas](#geo-partitioned-replicas) - -{{site.data.alerts.callout_success}} -You can check the state of any schema object's replication zone configuration at any time using [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}). -{{site.data.alerts.end}} - -#### Duplicate indexes - -If you used the duplicate indexes pattern, the steps for backing out the old configuration are: - -1. Remove the replication zone configurations you added using the [`ALTER DATABASE ... CONFIGURE ZONE DISCARD`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement. Note that this will remove all zone configurations from the table. If you had any additional customizations beyond what are required for the duplicate indexes pattern, you will have to reapply them. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE postal_codes CONFIGURE ZONE DISCARD; - ~~~ - -1. Drop the extra indexes you added. This will have the side effect of also deleting the zone configurations you added to those indexes. - - {% include_cached copy-clipboard.html %} - ~~~ sql - DROP INDEX postal_codes@idx_central; - DROP INDEX postal_codes@idx_east; - ~~~ - -The latency and resiliency benefits of the duplicate indexes pattern can be replaced by making `postal_codes` a [`GLOBAL` table]({% link {{ page.version.version }}/global-tables.md %}) with a [survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) that meets your needs. - -#### Geo-partitioned replicas - -If you applied the geo-partitioned replicas pattern, the steps for backing out the old configuration are: - -1. Remove the manually created table partition. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE users PARTITION BY NOTHING; - ~~~ - -1. Remove the manually created partition on the secondary indexes. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER INDEX users_last_name_index PARTITION BY NOTHING; - ~~~ - -The latency and resiliency benefits of the geo-partitioned replicas pattern can be replaced by making `users` a [`REGIONAL BY ROW` table]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -{{site.data.alerts.callout_info}} -The multi-region SQL abstractions use a hidden [`crdb_region`]({% link {{ page.version.version }}/alter-table.md %}#set-locality) column to represent the row's home region. You may need to modify your existing schema to take this into account. For example, if you already have a column you are using to denote each row's home region, you can use that name instead of `crdb_region` by following the instructions on the [`ALTER TABLE ... SET LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#set-locality) page. -{{site.data.alerts.end}} - -#### Geo-partitioned leaseholders - -If you applied the geo-partitioned leaseholders pattern, the steps for backing out the old configuration are: - -1. Remove the manually created table partition. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE users PARTITION BY NOTHING; - ~~~ - -1. Remove the manually created partition on the secondary indexes. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER INDEX users_last_name_index PARTITION BY NOTHING; - ~~~ - -The latency and resiliency benefits of the geo-partitioned leaseholders pattern can be replaced by making `users` a [`REGIONAL BY ROW` table]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 2. Add a primary region to your database - -The steps from this point forward assume that you have cleared your prior replication zone configurations and will be using the [multi-region SQL abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}) to work with a cluster that has existing [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions). - -Every multi-region database needs to have a primary region. To set the primary region, issue the [ALTER DATABASE ... SET PRIMARY REGION]({% link {{ page.version.version }}/alter-database.md %}#set-primary-region) statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo SET PRIMARY REGION = "us-west1" -~~~ - -### Step 3. Add more regions to the database - -To add another region to the database, issue the [`ADD REGION`]({% link {{ page.version.version }}/alter-database.md %}#add-region) statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo ADD REGION "us-central1"; -~~~ - -### Step 4. (Optional) Configure your database survival goal - -Depending on your desired database [survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals), you can choose from the following settings: - -- [`ZONE` survival]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) (Default): the database will remain fully available for reads and writes if one zone in a region goes down. More than one zone going down concurrently may affect availability. -- [`REGION` survival]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals): the database will remain fully available for reads and writes if one region goes down. More than one region going down concurrently may affect availability. - -For example, to set a region survival goal, issue the following SQL statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo SURVIVE REGION FAILURE; -~~~ - -For more information about when to use `ZONE` vs. `REGION` survival goals, see [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 5. Configure table localities - -For each table in your database, apply the [table locality]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) that provides the latency and resiliency requirements you need for that table. - -As described in [Replication zone patterns and multi-region SQL abstractions](#replication-zone-patterns-and-multi-region-sql-abstractions), the mapping from legacy replication zone patterns to multi-region SQL abstractions is: - -{% include {{page.version.version}}/sql/replication-zone-patterns-to-multiregion-sql-mapping.md %} - -For example, to configure the `postal_codes` table from the [duplicate indexes example](#duplicate-indexes) to use [multi-region SQL]({% link {{ page.version.version }}/multiregion-overview.md %}), you would enter the following statements to make the `postal_codes` table a [`GLOBAL` table]({% link {{ page.version.version }}/global-tables.md %}): - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER TABLE postal_codes SET LOCALITY GLOBAL; -~~~ - -For more information about when to use `GLOBAL` vs. `REGIONAL` tables, see [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 6. (Optional) View the updated zone configurations - -The multi-region SQL statements operate on the same replication zone configurations that you have access to via the [`ALTER TABLE ... CONFIGURE ZONE`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement. If you are interested in seeing how they work with the lower-level zone config mechanisms, you can use the [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}) statement to view the zone configurations. - -For example, given a multi-region demo cluster set up using the instructions in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), here is what the zone configs for several tables in the [MovR schema]({% link {{ page.version.version }}/movr.md %}) look like. - -#### Regional by row tables - -A [`REGIONAL BY ROW`]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) table differs from the default by setting the following zone configuration settings: - -- [`num_replicas`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_replicas) -- [`num_voters`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_voters) -- [`constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#constraints) -- [`voter_constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#voter_constraints) -- [`lease_preferences`]({% link {{ page.version.version }}/configure-replication-zones.md %}#lease_preferences) - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE users; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------------------------------------------------------- - DATABASE movr | ALTER DATABASE movr CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 5, - | num_voters = 3, - | constraints = '{+region=europe-west1: 1, +region=us-east1: 1, +region=us-west1: 1}', - | voter_constraints = '[+region=us-east1]', - | lease_preferences = '[[+region=us-east1]]' -(1 row) -~~~ - -The same table, loaded in a demo cluster with no zone configuration changes, looks like this: - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE users; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------- - RANGE default | ALTER RANGE default CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 3, - | constraints = '[]', - | lease_preferences = '[]' -(1 row) - -~~~ - -{{site.data.alerts.callout_danger}} -{% include {{page.version.version}}/known-limitations/secondary-regions-with-regional-by-row-tables.md %} -{{site.data.alerts.end}} - -#### Global tables - -A [`GLOBAL`]({% link {{ page.version.version }}/table-localities.md %}) table differs from the default by setting the following zone configuration settings: - -- [`global_reads`]({% link {{ page.version.version }}/configure-replication-zones.md %}#global_reads) -- [`num_replicas`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_replicas) -- [`num_voters`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_voters) -- [`constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#constraints) -- [`voter_constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#voter_constraints) -- [`lease_preferences`]({% link {{ page.version.version }}/configure-replication-zones.md %}#lease_preferences) - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE promo_codes; -~~~ - -~~~ - target | raw_config_sql ---------------------+------------------------------------------------------------------------------------------- - TABLE promo_codes | ALTER TABLE promo_codes CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | global_reads = true, - | num_replicas = 5, - | num_voters = 3, - | constraints = '{+region=europe-west1: 1, +region=us-east1: 1, +region=us-west1: 1}', - | voter_constraints = '[+region=us-east1]', - | lease_preferences = '[[+region=us-east1]]' -(1 row) -~~~ - -The same table, loaded in a demo cluster with no zone configuration changes, looks like this: - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE promo_codes; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------- - RANGE default | ALTER RANGE default CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 3, - | constraints = '[]', - | lease_preferences = '[]' -(1 row) -~~~ - -## See also - -- [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [When to use zone vs. region survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) -- [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) -- [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Configure Replication Zones]({% link {{ page.version.version }}/configure-replication-zones.md %}) -- [Non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) -- [Troubleshoot Replication Zones]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}) diff --git a/src/current/v26.1/movr.md b/src/current/v26.1/movr.md index 024525eceb2..718408229df 100644 --- a/src/current/v26.1/movr.md +++ b/src/current/v26.1/movr.md @@ -91,10 +91,6 @@ $ cockroach demo movr {% include {{ page.version.version }}/misc/movr-workflow.md %} -## Extended examples - -For a tutorial on running MovR against a multi-region cluster, using two important multi-region [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to get very low latency reads and writes, see [Low Latency, Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## See also - [Features in Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}) diff --git a/src/current/v26.1/multiregion-overview.md b/src/current/v26.1/multiregion-overview.md index 93fa6a82721..7e01b78913a 100644 --- a/src/current/v26.1/multiregion-overview.md +++ b/src/current/v26.1/multiregion-overview.md @@ -178,8 +178,6 @@ For more information, see [Zone Config Extensions]({% link {{ page.version.versi - [Global Tables]({% link {{ page.version.version }}/global-tables.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`ALTER DATABASE ... DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) - [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) diff --git a/src/current/v26.1/multiregion-scale-application.md b/src/current/v26.1/multiregion-scale-application.md index 04f062e28b5..9963ec9b3ed 100644 --- a/src/current/v26.1/multiregion-scale-application.md +++ b/src/current/v26.1/multiregion-scale-application.md @@ -85,7 +85,7 @@ For most table localities, including the default locality `LOCALITY REGIONAL BY However, there are some scenarios in which you might need to update the SQL operations in your application. For example: -- If a table has a `REGIONAL BY ROW AS ` table locality, and you want to explicitly insert regional values into a table, as shown in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#configure-regional-by-row-tables). +- If a table has a `REGIONAL BY ROW AS ` table locality, and you want to explicitly insert regional values into a table. - If a table has a `REGIONAL BY ROW` locality, and you want to update the `crdb_region` value of existing rows in the table based on some other column value, as shown in [Set the table locality to `REGIONAL BY ROW`]({% link {{ page.version.version }}/alter-table.md %}#set-the-table-locality-to-regional-by-row). - If a table has a `REGIONAL BY ROW` locality, and you want to filter a [selection query]({% link {{ page.version.version }}/select-clause.md %}#filter-rows) based on the `crdb_region` value. @@ -147,4 +147,3 @@ In the absence of an explicit, back-filling computed column for the hidden `crdb ## See also - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) diff --git a/src/current/v26.1/multiregion-survival-goals.md b/src/current/v26.1/multiregion-survival-goals.md index b49ee8544dc..bffb3b9ba12 100644 --- a/src/current/v26.1/multiregion-survival-goals.md +++ b/src/current/v26.1/multiregion-survival-goals.md @@ -63,10 +63,8 @@ Set a [`REGION` survival goal]({% link {{ page.version.version }}/multiregion-su + [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) + [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [Table Localities]({% link {{ page.version.version }}/table-localities.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.1/performance-benchmarking-with-tpcc-large.md b/src/current/v26.1/performance-benchmarking-with-tpcc-large.md deleted file mode 100644 index 1511dc246f5..00000000000 --- a/src/current/v26.1/performance-benchmarking-with-tpcc-large.md +++ /dev/null @@ -1,456 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C with 81 nodes on `c5d.9xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-100k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- [Review TPC-C concepts](#review-tpc-c-concepts) -- [Request a trial license](#request-a-trial-license) - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -### Request a trial license - -Reproducing these TPC-C results involves using CockroachDB's [partitioning]({% link {{ page.version.version }}/partitioning.md %}) feature to ensure replicas for any given section of data are located on the same nodes that will be queried by the load generator for that section of data. Partitioning helps distribute the workload evenly across the cluster. - -The partitioning feature requires an Enterprise license, so [request a 30-day trial license](https://www.cockroachlabs.com/get-cockroachdb/enterprise/) before you get started. - -You should receive your trial license via email within a few minutes. You'll enable your license once your cluster is up-and-running. - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 86 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 81 for CockroachDB nodes and 5 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.9xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Start CockroachDB using the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 \ - --locality=rack=0 - ~~~ - - Each node will start with a [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) that includes an artificial "rack number" (e.g., `--locality=rack=0`). Use 81 racks for 81 nodes so that 1 node will be assigned to each rack. - -1. Repeat these steps for the other 80 VMs for CockroachDB nodes. Each time, be sure to: - - Adjust the `--advertise-addr` flag. - - Set the [`--locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality) flag to the appropriate "rack number". - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Configure the cluster - -You'll be importing a large TPC-C data set. To speed that up, you can temporarily disable replication and tweak some cluster settings. You'll also need to enable the Enterprise license you requested earlier. - -1. SSH to any VM with the `cockroach` binary. - -1. Launch the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=
    - ~~~ - -1. Adjust some [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ sql - SET CLUSTER SETTING kv.dist_sender.concurrency_limit = 2016; - SET CLUSTER SETTING kv.snapshot_rebalance.max_rate = '256 MiB'; - SET CLUSTER SETTING sql.stats.automatic_collection.enabled = false; - SET CLUSTER SETTING schemachanger.backfiller.max_buffer_size = '5 GiB'; - SET CLUSTER SETTING rocksdb.min_wal_sync_interval = '500us'; - SET CLUSTER SETTING kv.range_merge.queue_enabled = false - ~~~ - -1. Change the default [GC TTL]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds) to the following value: - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 600; - ~~~ - -1. Enable the trial license you requested earlier: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING cluster.organization = ''; - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING enterprise.license = ''; - ~~~ - -1. Exit the SQL shell: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > \q - ~~~ - -## Step 4. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --replicate-static-columns \ - --partition-strategy=leases \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 11.2 TB of data for 140,000 "warehouses". This can take up to 8 hours to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 5. Partition the database - -1. [Partition your database]({% link {{ page.version.version }}/partitioning.md %}) to divide all of the TPC-C tables and indexes into 81 partitions, one per rack, and then use [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) to pin those partitions to a particular rack. - -1. Wait for up-replication and partitioning to finish. You will know when they have finished because both the number of *lease transfers* and *snapshots* will go down to `0` and stay there. This will likely take 10s of minutes. - - To monitor the number of lease transfers, open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}), select the **Replication** dashboard, hover over the **Range Operations** graph, and check the **Lease Transfers** data point. - - To check the number of snapshots, open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}), select the **Replication** dashboard, and hover over the **Snapshots** graph. - - TPC-C 140k replication and partitioning dashboards - -## Step 7. Allocate partitions - -Before running the benchmark, it's important to allocate partitions to workload binaries properly to ensure that the cluster is balanced. - -1. Create an `addrs` file containing connection strings to all 81 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable ... - ~~~ - -1. Upload the `addrs` file to the 5 VMs with the `workload` binary: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - -1. SSH to each VM with `workload` and allocate partitions: - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload1.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions 81 \ - --warehouses 140000 \ - --partition-affinity=17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload2.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload3.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload4.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload5.histogram.ndjson \ - $(cat addrs) - ~~~ - -## Step 8. Run the benchmark - -Once the allocations finish, run TPC-C for 30 minutes on each VM with `workload`: - -{{site.data.alerts.callout_info}} -It is critical to run the benchmark from the workload nodes in parallel, so start them as simultaneously as possible. -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload1.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload2.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload3.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload4.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partition=81 \ ---warehouses=140000 \ ---partition-affinity=65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload5.histogram.ndjson \ -$(cat addrs) -~~~ - -## Step 9. Interpret the results - -1. Collect the result files from each VM with `workload`: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload1.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload2.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload3.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload4.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload5.histogram.ndjson . - ~~~ - -1. Upload the result files to one of the VMs with the `workload` binary: - - {{site.data.alerts.callout_info}} - The following commands assume you're uploading to the VM with the `workload1.histogram.ndjson` file. - {{site.data.alerts.end}} - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload2.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload3.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload4.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload5.histogram.ndjson @:. - ~~~ - -1. SSH to the VM where you uploaded the results files. - -1. Run the `workload debug tpcc-merge-results` command to synthesize the results: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach workload debug tpcc-merge-results \ - --warehouses=140000 \ - workload*.histogram.ndjson - ~~~ - - You'll should see results similar to the following, with **1.68M tpmC with 140,000 warehouses, resulting in an efficiency score of 95%**: - - ~~~ - Duration: 30m1., Warehouses: 140000, Efficiency: 95.45, tpmC: 1684437.21 - _elapsed___ops/sec(cum)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1801.1s 2824.0 302.0 1140.9 2415.9 9126.8 55834.6 delivery - 1801.1s 28074.0 402.7 1409.3 2684.4 9126.8 45097.2 newOrder - 1801.1s 2826.0 6.8 62.9 125.8 4160.7 33286.0 orderStatus - 1801.1s 28237.4 251.7 1006.6 2415.9 15032.4 103079.2 payment - 1801.1s 2823.5 39.8 469.8 906.0 5905.6 38654.7 stockLevel - ~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.1/performance-benchmarking-with-tpcc-local-multiregion.md b/src/current/v26.1/performance-benchmarking-with-tpcc-local-multiregion.md deleted file mode 100644 index 8b8d05d6f7d..00000000000 --- a/src/current/v26.1/performance-benchmarking-with-tpcc-local-multiregion.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to run the TPC-C benchmark against CockroachDB -toc: true -toc_not_nested: true -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|--------------------------+-------------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -- Make sure you have already [installed CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}). - -## Step 1. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -In the terminal, use the [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) command to start a simulated multi-region cluster with 9 nodes: - -{% include_cached copy-clipboard.html %} -~~~ shell -cockroach demo --global --nodes 9 --no-example-database --insecure -~~~ - -This simulated multi-region deployment will take advantage of CockroachDB's [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) to deliver improved ease of use and performance. - -{{site.data.alerts.callout_info}} -You must use the IP address shown at the SQL prompt to run the following steps. - -This is necessary because the demo cluster may use a randomly allocated local IP that is not the `127.0.0.1` shown here. -{{site.data.alerts.end}} - -## Step 2. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -In a second terminal window (call it terminal 2), use [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}) to load the initial schema and data: - -{% include_cached copy-clipboard.html %} -~~~ shell -cockroach workload init tpcc \ ---warehouses=10 \ ---partitions=3 \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26257/tpcc?sslmode=disable' -~~~ - -This will load 2 GB of data for 10 "warehouses", and spread the data across all 3 regions with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#survive-zone-failures). - -## Step 3. Run the benchmark - -Run the workload for 10 "warehouses" of data for ten minutes. In order to spread the simulated workload across the 3 regions specified in the previous step, you will need to start each of the following commands from 3 different terminals: - -In terminal 2: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=0 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26257/tpcc?sslmode=disable' -~~~ - -In terminal 3: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=1 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26260/tpcc?sslmode=disable' -~~~ - -In terminal 4: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=2 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26263/tpcc?sslmode=disable' -~~~ - -You'll see per-operation statistics every second: - -~~~ -Initializing 20 connections... -Initializing 100 workers and preparing statements... -_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 delivery - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 newOrder -... - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 delivery - 105.0s 0 4.0 1.8 44.0 46.1 46.1 46.1 newOrder - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 orderStatus - 105.0s 0 1.0 2.0 14.7 14.7 14.7 14.7 payment - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 stockLevel -... -~~~ - -{{site.data.alerts.callout_success}} -For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other built-in load generators, use `cockroach workload run --help`. -{{site.data.alerts.end}} - -## Step 4. Interpret the results - -Once the `workload` has finished running, you'll see a final output line in each terminal window. - -In terminal 2: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 33.2% 170.6 44.0 536.9 872.4 1543.5 3087.0 -~~~ - -In terminal 3: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 28.4% 147.0 41.9 453.0 671.1 1342.2 1946.2 -~~~ - -In terminal 4: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 28.4% 222.8 46.1 704.6 1140.9 1744.8 2952.8 -~~~ - -You will also see some audit checks and latency statistics for each individual query in each terminal. Some of those checks might indicate that they were `SKIPPED` due to insufficient data since this is a small run on a small machine. For a more comprehensive test, run `workload` for a longer duration (e.g., two hours). The `tpmC` (new order transactions/minute) number is the headline number and `efc` ("efficiency") tells you how close CockroachDB gets to theoretical maximum `tpmC`. In a perfect execution, the sum of efficiency across all partitions would be 100%. - -## Step 5. Clean up - -When you're done with your test cluster, switch back to terminal 1 where [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) is still running and issue `\q` at the SQL prompt to gracefully shut down the demo cluster. - -{% include_cached copy-clipboard.html %} -~~~ sql -\q -~~~ diff --git a/src/current/v26.1/performance-benchmarking-with-tpcc-local.md b/src/current/v26.1/performance-benchmarking-with-tpcc-local.md deleted file mode 100644 index 133bab2d3dd..00000000000 --- a/src/current/v26.1/performance-benchmarking-with-tpcc-local.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C 13k on 3 nodes on your laptop -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-10-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -- Make sure you have already [installed CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}). - -## Step 1. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. In separate terminal windows, use the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command to start 3 nodes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local1 \ - --listen-addr=localhost:26257 \ - --http-addr=localhost:8080 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local2 \ - --listen-addr=localhost:26258 \ - --http-addr=localhost:8081 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local3 \ - --listen-addr=localhost:26259 \ - --http-addr=localhost:8082 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - -1. Use the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to perform a one-time initialization of the cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach init \ - --insecure \ - --host=localhost:26257 - ~~~ - -## Step 2. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -Use [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}) to load the initial schema and data: - -{% include_cached copy-clipboard.html %} -~~~ shell -$ cockroach workload fixtures import tpcc \ ---warehouses=10 \ -'postgresql://root@localhost:26257?sslmode=disable' -~~~ - -This will load 2 GB of data for 10 "warehouses". - -## Step 3. Run the benchmark - -Run the workload for ten "warehouses" of data for ten minutes: - -{% include_cached copy-clipboard.html %} -~~~ shell -$ cockroach workload run tpcc \ ---warehouses=10 \ ---ramp=3m \ ---duration=10m \ -'postgresql://root@localhost:26257?sslmode=disable' -~~~ - -You'll see per-operation statistics every second: - -~~~ -Initializing 20 connections... -Initializing 100 workers and preparing statements... -_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 delivery - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 newOrder -... - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 delivery - 105.0s 0 4.0 1.8 44.0 46.1 46.1 46.1 newOrder - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 orderStatus - 105.0s 0 1.0 2.0 14.7 14.7 14.7 14.7 payment - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 stockLevel -... -~~~ - -{{site.data.alerts.callout_success}} -For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other built-in load generators, use `cockroach workload run --help`. -{{site.data.alerts.end}} - -## Step 4. Interpret the results - -Once the `workload` has finished running, you'll see a final output line: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 300.0s 121.6 94.6% 41.0 39.8 54.5 71.3 96.5 130.0 -~~~ - -You will also see some audit checks and latency statistics for each individual query. For this run, some of those checks might indicate that they were `SKIPPED` due to insufficient data. For a more comprehensive test, run `workload` for a longer duration (e.g., two hours). The `tpmC` (new order transactions/minute) number is the headline number and `efc` ("efficiency") tells you how close CockroachDB gets to theoretical maximum `tpmC`. - -The [TPC-C specification](http://www.tpc.org/tpc_documents_current_versions/pdf/tpc-c_v5.11.0.pdf) has p90 latency requirements in the order of seconds, but as you see here, CockroachDB far surpasses that requirement with p90 latencies in the tens of milliseconds. - -## Step 5. Clean up - -1. When you're done with your test cluster, stop the nodes. - - Get the process IDs of the nodes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - ps -ef | grep cockroach | grep -v grep - ~~~ - - ~~~ - 501 4482 1 0 2:41PM ttys000 0:09.78 cockroach start --insecure --store=tpcc-local1 --listen-addr=localhost:26257 --http-addr=localhost:8080 --join=localhost:26257,localhost:26258,localhost:26259 - 501 4497 1 0 2:41PM ttys000 0:08.54 cockroach start --insecure --store=tpcc-local2 --listen-addr=localhost:26258 --http-addr=localhost:8081 --join=localhost:26257,localhost:26258,localhost:26259 - 501 4503 1 0 2:41PM ttys000 0:08.54 cockroach start --insecure --store=tpcc-local3 --listen-addr=localhost:26259 --http-addr=localhost:8082 --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - Gracefully shut down each node, specifying its process ID: - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4482 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4497 - ~~~ - - {{site.data.alerts.callout_info}} - For the last node, the shutdown process will take longer (about a minute) and will eventually stop the node. This is because, with only 1 of 3 nodes left, all ranges no longer have a majority of replicas available, and so the cluster is no longer operational. - {{site.data.alerts.end}} - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4503 - ~~~ - -1. To restart the cluster at a later time, run the same `cockroach start` commands as earlier from the directory containing the nodes' data stores. - - If you do not plan to restart the cluster, you may want to remove the nodes' data stores: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ rm -rf tpcc-local1 tpcc-local2 tpcc-local3 - ~~~ diff --git a/src/current/v26.1/performance-benchmarking-with-tpcc-medium.md b/src/current/v26.1/performance-benchmarking-with-tpcc-medium.md deleted file mode 100644 index 17433899aba..00000000000 --- a/src/current/v26.1/performance-benchmarking-with-tpcc-medium.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Benchmark CockroachDB against TPC-C with 15 nodes on `c5d.4xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-10k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- [Review TPC-C concepts](#review-tpc-c-concepts) -- [Request a trial license](#request-a-trial-license) - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -### Request a trial license - -Reproducing these TPC-C results involves using CockroachDB's [partitioning]({% link {{ page.version.version }}/partitioning.md %}) feature to ensure replicas for any given section of data are located on the same nodes that will be queried by the load generator for that section of data. Partitioning helps distribute the workload evenly across the cluster. - -The partitioning feature requires an Enterprise license, so [request a 30-day trial license](https://www.cockroachlabs.com/get-cockroachdb/enterprise/) before you get started. - -You should receive your trial license via email within a few minutes. You'll enable your license once your cluster is up-and-running. - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 16 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 15 for CockroachDB nodes and 1 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.4xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Run the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 \ - --locality=rack=0 - ~~~ - - Each node will start with a [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) that includes an artificial "rack number" (e.g., `--locality=rack=0`). Use 5 racks for 15 nodes so that 3 nodes will be assigned to each rack. - -1. Repeat steps 1 - 3 for the other 14 VMs for CockroachDB nodes. Each time, be sure to: - - Adjust the `--advertise-addr` flag. - - Set the [`--locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality) flag to the appropriate "rack number". - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Configure the cluster - -You'll be importing a large TPC-C data set. To speed that up, you can tweak some cluster settings. You'll also need to enable the Enterprise license you requested earlier. - -1. SSH to any VM with the `cockroach` binary. - -1. Launch the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=
    - ~~~ - -1. Adjust some [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING rocksdb.ingest_backpressure.l0_file_count_threshold = 100; - SET CLUSTER SETTING schemachanger.backfiller.max_buffer_size = '5 GiB'; - SET CLUSTER SETTING kv.snapshot_rebalance.max_rate = '128 MiB'; - SET CLUSTER SETTING rocksdb.min_wal_sync_interval = '500us'; - SET CLUSTER SETTING kv.range_merge.queue_enabled = false; - ~~~ - -1. Enable the trial license you requested earlier: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING cluster.organization = ''; - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING enterprise.license = ''; - ~~~ - -1. Exit the SQL shell: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > \q - ~~~ - -## Step 4. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --partitions=5 \ - --warehouses=13000 \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 1.04 TB of data for 13,000 "warehouses". This can take around 1 hour to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 5. Allow the cluster to rebalance - -Next, [partition your database]({% link {{ page.version.version }}/partitioning.md %}) to divide all of the TPC-C tables and indexes into 5 partitions, one per rack, and then use [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) to pin those partitions to a particular rack. - -1. Still on the same VM, briefly run TPC-C to let the cluster balance and the leases settle. Bump the file descriptor limits with `ulimit` to the high value shown in the following snippet, since the workload generators create a lot of database connections. - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ ulimit -n 100000 && cockroach workload run tpcc \ - --partitions=5 \ - --warehouses=13000 \ - --duration=1m \ - --ramp=1ms \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - -1. Wait for range rebalancing to finish. - - This will likely take 10s of minutes. To watch the progress, go to the **Metrics > Queues > Replication Queue** graph in the DB Console. Once the **Replication Queue** gets to `0` for all actions and stays there, you can move on to the next step. - -## Step 6. Run the benchmark - -1. Back on the VM with the `workload` binary, create an `addrs` file containing connection strings to all 15 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable ... - ~~~ - -1. Run TPC-C for 30 minutes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ ulimit -n 100000 && cockroach workload run tpcc \ - --partitions=5 \ - --warehouses=13000 \ - --ramp=1m \ - --duration=30m \ - $(cat addrs) - ~~~ - -## Step 7. Interpret the results - -Once the workload has finished running, you will see a result similar to the following. The efficiency and latency can be combined to determine whether this was a passing run. You should expect to see an efficiency number above 95%, well above the required minimum of 85%, and p95 latencies well below the required maximum of 10 seconds. - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1800.0s 160420.0 96.0% 303.1 285.2 570.4 671.1 939.5 4160.7 -~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.1/performance-benchmarking-with-tpcc-small.md b/src/current/v26.1/performance-benchmarking-with-tpcc-small.md deleted file mode 100644 index a6c32eef6a4..00000000000 --- a/src/current/v26.1/performance-benchmarking-with-tpcc-small.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C with 3 nodes on `c5d.4xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-1k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 4 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 3 for CockroachDB nodes and 1 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.4xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Run the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 - ~~~ - -1. Repeat steps 1 - 3 for the other 2 VMs for CockroachDB nodes. Each time, be sure to adjust the `--advertise-addr` flag. - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --warehouses=2500 \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 200 GB of data for 2500 "warehouses". This can take a while to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 4. Run the benchmark - -1. Still on the same VM, create an `addrs` file containing connection strings to the 3 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable - ~~~ - -1. Run TPC-C for 30 minutes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload run tpcc \ - --warehouses=2500 \ - --ramp=1m \ - --duration=30m \ - $(cat addrs) - ~~~ - -## Step 5. Interpret the results - -Once the workload has finished running, you will see a result similar to the following. The efficiency and latency can be combined to determine whether this was a passing run. You should expect to see an efficiency number above 95%, well above the required minimum of 85%, and p95 latencies well below the required maximum of 10 seconds. - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1800.0s 31064.6 96.6% 107.4 88.1 243.3 302.0 402.7 973.1 -~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.1/performance.md b/src/current/v26.1/performance.md deleted file mode 100644 index 6a3592849ca..00000000000 --- a/src/current/v26.1/performance.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Benchmarking Overview -summary: An overview of the performance profiles you can expect from CockroachDB. -toc: true -toc_not_nested: true -docs_area: reference.benchmarking ---- - -CockroachDB delivers predictable throughput and latency at all scales on commodity hardware. This page provides an overview of the performance profiles you can expect, based on Cockroach Labs's extensive testing using the TPC-C industry-standard benchmark. - -For instructions to reproduce the TPC-C results listed here, see [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-large.md %}). If you fail to achieve similar results, there is likely a problem in either the hardware, workload, or test design. - -{{site.data.alerts.callout_success}} -This document is about CockroachDB performance on benchmarks. For guidance on tuning real workloads, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on data location techniques to minimize network latency, see [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}). -{{site.data.alerts.end}} - -## Scale - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. During testing, CockroachDB v21.1 processed **1.68M tpmC with 140,000 warehouses, resulting in an efficiency score of 95%.** As shown in the following chart, this was a 40% improvement over the results from CockroachDB 19.2. - -For a refresher on what exactly TPC-C is and how it is measured, see [Benchmark details](#benchmark-details). - -CockroachDB achieves this performance in [`SERIALIZABLE` isolation]({% link {{ page.version.version }}/demo-serializable.md %}), the strongest isolation level in the SQL standard. - -TPC-C 140,000 - -| Metric | CockroachDB 19.2 | CockroachDB 21.1 | -|-------------------------------------------------+------------------+------------------| -| Max warehouses with max efficiency (warehouses) | 100,000 | 140,000 | -| Max throughput (tpmC) | 1,245,462 | 1,684,437 | -| Efficiency (%) | 98.81 | 95.45 | -| Max number of rows (billion) | 49.8 | 69.7 | -| Max unreplicated data (TB) | 8 | 11.2 | -| Number of nodes | 81 | 81 | - -### Linear scaling - -CockroachDB has **no theoretical scaling limit** and, in practice, can achieve near-linear performance at 256 nodes. Because the TPC-C results reflect leaps in scale, to test linear scaling, Cockroach Labs ran a simple benchmark named KV 95 (95% point reads, 5% point writes, all uniformly distributed) on AWS `c5d.4xlarge` machines: - -CRDB Linear Scale - -This chart shows that adding nodes increases throughput linearly while holding p50 and p99 latency constant. The concurrency for each scale was chosen to optimize throughput while maintaining an acceptable latency and can be observed in the following table. - -| Number of nodes | Workers | Concurrency | -|-----------------+---------+-------------| -| 16 | 2 | 512 | -| 32 | 4 | 512 | -| 64 | 4 | 1024 | -| 128 | 8 | 1024 | -| 256 | 8 | 2048 | - -## Throughput - -Cockroach Labs believes TPC-C provides the most realistic and objective measure for OLTP throughput. In the real world, applications generate transactional workloads that consist of a combination of reads and writes, possibly with concurrency and likely without all data being loaded into memory. Approach benchmark results quoted in QPS with caution, because anything as simple as a “query” is unlikely to be representative of the workload you need to run in practice. - -## Latency - -CockroachDB returns single-row **reads in 1 ms** and processes single-row **writes in 2 ms** within a single availability zone. As you expand out to multiple availability zones or multiple regions, latency can increase due to distance and the limitation of the speed of light. - -For benchmarking latency, again, Cockroach Labs believes TPC-C provides the most realistic and objective measure, since it encompasses the latency distribution, including tail performance. - -CockroachDB provides a number of important tuning practices for both single-region and multi-region deployments, including [secondary indexes]({% link {{ page.version.version }}/indexes.md %}) and various [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to achieve low latency. - -## Benchmark details - -### TPC-C - -Cockroach Labs measures performance through many diverse tests, including the [industry-standard OLTP benchmark TPC-C](http://www.tpc.org/tpcc/), which simulates an e-commerce or retail company. Created in 1992, TPC-C has withstood the test of time and remains the most mature industry benchmark for OLTP workloads, and **the only objective comparison for evaluating OLTP performance**. In its own words, TPC-C: - ->“…involves a mix of five concurrent transactions of different types and complexity either executed on-line or queued for deferred execution. The database is comprised of nine types of tables with a wide range of record and population sizes. While the benchmark portrays the activity of a wholesale supplier, TPC-C is not limited to the activity of any particular business segment, but, rather represents any industry that must manage, sell, or distribute a product or service.” - -As a result, TPC-C includes create, read, update, and delete (e.g., CRUD) queries, basic joins, and other SQL statements used to administer mission-critical transactional workloads. It includes detailed specifications for concurrency and workload [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention). - -#### How TPC-C works - -TPC-C measures the throughput and latency for processing sales through a customer warehouse using a “business throughput” metric called **tpmC** that measures the number of order transactions performed per minute throughout the system. This metric is considerably more realistic than TPS (transactions per second) or QPS (queries per second) alone because it summarizes multiple transactions per order and accounts for failed transactions. TPC-C also has several latency requirements that apply to median, p90, and max latencies. - -TPC-C specifies restrictions on the maximum throughput achievable per warehouse. This is done to ensure that as a system becomes progressively more capable of throughput, it must also deal with progressively more data. This is how things work in the real world, and it makes little sense to say that your database can process a bazillion transactions per second if it’s processing the same data over and over again. - -Because TPC-C is constrained to a maximum amount of throughput per warehouse, we often discuss TPC-C performance as the **maximum number of warehouses for which a database can maintain the maximum throughput per minute.** For a full description of the benchmark, see [TPC BENCHMARK™ C Standard Specification Revision 5.11](http://www.tpc.org/tpc_documents_current_versions/pdf/tpc-c_v5.11.0.pdf). - -## Performance limitations - -CockroachDB has no theoretical limitations to scaling, throughput, latency, or concurrency other than the speed of light. - -## See also - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -- TPC-C replication instructions - - For instructions showing how to replicate the TPC-C results described in this page, see [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-large.md %}). diff --git a/src/current/v26.1/query-behavior-troubleshooting.md b/src/current/v26.1/query-behavior-troubleshooting.md index b72f677fe65..292a4f96b04 100644 --- a/src/current/v26.1/query-behavior-troubleshooting.md +++ b/src/current/v26.1/query-behavior-troubleshooting.md @@ -366,7 +366,7 @@ A response of `bad connection` or `closed` normally indicates that the node to w Once you find the node, you can check its [logs]({% link {{ page.version.version }}/logging.md %}) (stored in `cockroach-data/logs` by [default]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration)). -Because this kind of behavior is unexpected, you should [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). +Because this kind of behavior is unexpected, you should file an issue on Github. ### Log queries executed by a specific node diff --git a/src/current/v26.1/regional-tables.md b/src/current/v26.1/regional-tables.md index bd9a1bd3184..868e7e49e87 100644 --- a/src/current/v26.1/regional-tables.md +++ b/src/current/v26.1/regional-tables.md @@ -110,7 +110,7 @@ By default, all tables in a multi-region database are [regional tables](#regiona {% include {{page.version.version}}/sql/locality-optimized-search.md %} {{site.data.alerts.callout_success}} -A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. For a tutorial showing how table localities can improve performance metrics across a multi-region cluster, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. {{site.data.alerts.end}} ## Characteristics @@ -132,10 +132,6 @@ For more information about how to choose a database survival goal, see [When to - If rows in the table **cannot** be tied to specific geographies, reads must be up-to-date for business reasons or because the table is referenced by [foreign keys]({% link {{ page.version.version }}/foreign-key.md %}), and the table is rarely modified, consider the [`GLOBAL` Table Locality Pattern]({% link {{ page.version.version }}/global-tables.md %}). - If your application can tolerate historical reads in some cases, consider the [Follower Reads pattern]({% link {{ page.version.version }}/topology-follower-reads.md %}). -## Tutorial - -For a step-by-step demonstration showing how CockroachDB's multi-region capabilities (including [`REGIONAL BY ROW` tables](#regional-by-row-tables)) give you low-latency reads in a distributed cluster, see the tutorial on [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## Demo video If you'd prefer to watch a video on Regional Tables, check out the following video: diff --git a/src/current/v26.1/secure-a-cluster.md b/src/current/v26.1/secure-a-cluster.md index b4fc4e477b4..fabb95d7472 100644 --- a/src/current/v26.1/secure-a-cluster.md +++ b/src/current/v26.1/secure-a-cluster.md @@ -460,7 +460,7 @@ Adding capacity is as simple as starting more nodes with `cockroach start`. - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and JSON support({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and JSON support({% link {{ page.version.version }}/jsonb.md %}) You might also be interested in the following pages: diff --git a/src/current/v26.1/show-locality.md b/src/current/v26.1/show-locality.md index 82b2152eb80..983e50d381e 100644 --- a/src/current/v26.1/show-locality.md +++ b/src/current/v26.1/show-locality.md @@ -79,7 +79,6 @@ For a more extensive example, see [Create a table with node locality information ## See also -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) - [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %}) - [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) diff --git a/src/current/v26.1/show-partitions.md b/src/current/v26.1/show-partitions.md index c7f2e8a1bbd..528853f58ad 100644 --- a/src/current/v26.1/show-partitions.md +++ b/src/current/v26.1/show-partitions.md @@ -237,4 +237,3 @@ If a partitioned table has no zones configured, the `SHOW CREATE TABLE` output i - [Define Table Partitions]({% link {{ page.version.version }}/partitioning.md %}) - [SQL Statements]({% link {{ page.version.version }}/sql-statements.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) diff --git a/src/current/v26.1/simulate-a-multi-region-cluster-on-localhost.md b/src/current/v26.1/simulate-a-multi-region-cluster-on-localhost.md index f77db92ae17..6c84c2a96da 100644 --- a/src/current/v26.1/simulate-a-multi-region-cluster-on-localhost.md +++ b/src/current/v26.1/simulate-a-multi-region-cluster-on-localhost.md @@ -95,6 +95,5 @@ When you're done with your demo cluster, you can wipe the cluster by typing the - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - Further explore CockroachDB capabilities like: - - [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}) - [Serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}) diff --git a/src/current/v26.1/start-a-local-cluster-in-docker-linux.md b/src/current/v26.1/start-a-local-cluster-in-docker-linux.md index fe34cbaa255..4aca92a6ac4 100644 --- a/src/current/v26.1/start-a-local-cluster-in-docker-linux.md +++ b/src/current/v26.1/start-a-local-cluster-in-docker-linux.md @@ -37,4 +37,4 @@ Once you've [installed the official CockroachDB Docker image]({% link {{ page.ve - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.1/start-a-local-cluster-in-docker-mac.md b/src/current/v26.1/start-a-local-cluster-in-docker-mac.md index 8dabc54bc70..b929ec0b47f 100644 --- a/src/current/v26.1/start-a-local-cluster-in-docker-mac.md +++ b/src/current/v26.1/start-a-local-cluster-in-docker-mac.md @@ -34,4 +34,4 @@ Once you've [installed the official CockroachDB Docker image]({% link {{ page.ve - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.1/start-a-local-cluster-in-docker-windows.md b/src/current/v26.1/start-a-local-cluster-in-docker-windows.md index 97816cee25f..fc405bbc7cb 100644 --- a/src/current/v26.1/start-a-local-cluster-in-docker-windows.md +++ b/src/current/v26.1/start-a-local-cluster-in-docker-windows.md @@ -366,4 +366,4 @@ The CockroachDB [DB Console]({% link {{ page.version.version }}/ui-overview.md % - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.1/start-a-local-cluster.md b/src/current/v26.1/start-a-local-cluster.md index 86ab9aa356e..ff41d45e642 100644 --- a/src/current/v26.1/start-a-local-cluster.md +++ b/src/current/v26.1/start-a-local-cluster.md @@ -389,4 +389,4 @@ Adding capacity is as simple as starting more nodes with `cockroach start`. - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.1/support-resources.md b/src/current/v26.1/support-resources.md index d4ac13b822f..0474ef39a6c 100644 --- a/src/current/v26.1/support-resources.md +++ b/src/current/v26.1/support-resources.md @@ -13,6 +13,5 @@ If you're having an issue with CockroachDB, you can reach out for support from C - [CockroachDB Community Forum](https://forum.cockroachlabs.com) - [CockroachDB Community Slack](https://cockroachdb.slack.com) - [CockroachDB in StackOverflow](http://stackoverflow.com/questions/tagged/cockroachdb) -- [File an issue in GitHub]({% link {{ page.version.version }}/file-an-issue.md %}) We also rely on contributions from users like you. If you know how to help users who might be struggling with a problem, we hope you will! diff --git a/src/current/v26.1/table-localities.md b/src/current/v26.1/table-localities.md index ac711dc5030..9e84ecff1e9 100644 --- a/src/current/v26.1/table-localities.md +++ b/src/current/v26.1/table-localities.md @@ -66,10 +66,8 @@ Use a [`GLOBAL` table locality]({% link {{ page.version.version }}/table-localit - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) - [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.1/troubleshooting-overview.md b/src/current/v26.1/troubleshooting-overview.md index e4b911aadbd..ed015771ef2 100644 --- a/src/current/v26.1/troubleshooting-overview.md +++ b/src/current/v26.1/troubleshooting-overview.md @@ -26,7 +26,6 @@ If you experience an issue when using CockroachDB, try these steps to resolve th - If you cannot resolve the issue yourself, the following tools can help you move forward: - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) identify ways you can get help with troubleshooting. - - [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) provides details on how to file an issue that you're unable to resolve. - In a support escalation, you may be directed to use the following features by the [Cockroach Labs support team]({% link {{ page.version.version }}/support-resources.md %}): diff --git a/src/current/v26.1/ui-network-latency-page.md b/src/current/v26.1/ui-network-latency-page.md index e3dcf18a011..29e306d34b8 100644 --- a/src/current/v26.1/ui-network-latency-page.md +++ b/src/current/v26.1/ui-network-latency-page.md @@ -30,7 +30,7 @@ Rows represent origin nodes, and columns represent destination nodes. Hover over The page automatically refreshes every 30 seconds to show the most recent information. -On a [typical multi-region cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), you can expect much lower latencies between nodes in the same region/availability zone. Nodes in different regions/availability zones, meanwhile, will experience higher latencies that reflect their geographical distribution. +On a [typical multi-region cluster]({% link {{ page.version.version }}/multiregion-overview.md %}), you can expect much lower latencies between nodes in the same region/availability zone. Nodes in different regions/availability zones, meanwhile, will experience higher latencies that reflect their geographical distribution. For instance, the cluster shown above has nodes in `us-west1`, `us-east1`, and `europe-west2`. Latencies are highest between nodes in `us-west1` and `europe-west2`, which span the greatest distance. This is especially clear when sorting by region or availability zone and collapsing nodes: @@ -81,6 +81,4 @@ Network latency limits the performance of individual operations. You can use the ## See also - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) -- [CockroachDB Performance]({% link {{ page.version.version }}/performance.md %}#latency) - [Performance Tuning]({% link {{ page.version.version }}/performance-best-practices-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) diff --git a/src/current/v26.2/alter-database.md b/src/current/v26.2/alter-database.md index 278a88479b0..758aed130c8 100644 --- a/src/current/v26.2/alter-database.md +++ b/src/current/v26.2/alter-database.md @@ -729,7 +729,7 @@ ALTER DATABASE movr CONFIGURE ZONE USING range_min_bytes = 0, range_max_bytes = {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the multi-region abstractions created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} @@ -1202,7 +1202,7 @@ To follow along with the examples below: cockroach demo --global --nodes 9 ~~~ -1. Set the demo cluster's [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) as described in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) (specifically, starting at [Step 5. Execute multi-region SQL statements]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#step-5-execute-multi-region-sql-statements)). +1. Set the demo cluster's [database regions]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality). 1. Enable the replica placement syntax with either the [session variable]({% link {{ page.version.version }}/set-vars.md %}) or the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) as shown below. diff --git a/src/current/v26.2/alter-index.md b/src/current/v26.2/alter-index.md index ac4eb0722b6..ed21d190178 100644 --- a/src/current/v26.2/alter-index.md +++ b/src/current/v26.2/alter-index.md @@ -282,7 +282,7 @@ ALTER INDEX vehicles@vehicles_auto_index_fk_city_ref_users CONFIGURE ZONE USING {{site.data.alerts.callout_info}} When you discard a zone configuration, the objects it was applied to will then inherit a configuration from an object "the next level up"; e.g., if the object whose configuration is being discarded is a table, it will use its parent database's configuration. -You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region abstractions]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}#replication-zone-patterns-and-multi-region-sql-abstractions) created the zone configuration. +You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or partitions if the [multi-region] ({% link {{ page.version.version }}/multiregion-overview.md %}) created the zone configuration. {{site.data.alerts.end}} {% include_cached copy-clipboard.html %} diff --git a/src/current/v26.2/alter-table.md b/src/current/v26.2/alter-table.md index 36b96d3f07f..e03b1ccf00c 100644 --- a/src/current/v26.2/alter-table.md +++ b/src/current/v26.2/alter-table.md @@ -1315,7 +1315,7 @@ Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %} {% include {{page.version.version}}/sql/indexes-regional-by-row.md %} -This example assumes you have a simulated multi-region database running on your local machine following the steps described in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). It shows how a `UNIQUE` index is partitioned, but it's similar to how all indexes are partitioned on `REGIONAL BY ROW` tables. +This example assumes you have a simulated multi-region database running on your local machine. It shows how a `UNIQUE` index is partitioned, but it's similar to how all indexes are partitioned on `REGIONAL BY ROW` tables. To show how the automatic partitioning of indexes on `REGIONAL BY ROW` tables works, we will: @@ -1335,7 +1335,7 @@ ALTER TABLE users ADD COLUMN email STRING; ALTER TABLE users ADD CONSTRAINT user_email_unique UNIQUE (email); ~~~ -Next, issue the [`SHOW INDEXES`]({% link {{ page.version.version }}/show-index.md %}) statement. You will see that [the implicit region column](#set-the-table-locality-to-regional-by-row) that was added when the table [was converted to regional by row]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#configure-regional-by-row-tables) is now indexed: +Next, issue the [`SHOW INDEXES`]({% link {{ page.version.version }}/show-index.md %}) statement. You will see that [the implicit region column](#set-the-table-locality-to-regional-by-row) that was added when the table was converted to regional by row is now indexed: {% include_cached copy-clipboard.html %} ~~~ sql @@ -1700,7 +1700,7 @@ If the column has the [`NOT NULL` constraint]({% link {{ page.version.version }} #### Convert to a different data type -The [TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) database has a `customer` table with a column `c_credit_lim` of type `DECIMAL(10,2)`: +The TPC-C database has a `customer` table with a column `c_credit_lim` of type `DECIMAL(10,2)`: {% include_cached copy-clipboard.html %} ~~~ sql @@ -1740,7 +1740,7 @@ To change the data type from `DECIMAL` to `STRING`: #### Change a column type's precision -The [TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) `customer` table contains a column `c_balance` of type `DECIMAL(12,2)`: +The TPC-C `customer` table contains a column `c_balance` of type `DECIMAL(12,2)`: {% include_cached copy-clipboard.html %} ~~~ sql @@ -2896,7 +2896,7 @@ ALTER TABLE {table} ALTER COLUMN crdb_region SET ON UPDATE rehome_row()::db.publ ##### Example -1. Follow steps 1 and 2 from the [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) tutorial. This will involve starting a [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) cluster in a terminal window (call it _terminal 1_). +1. Start a [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) cluster in a terminal window (call it _terminal 1_). 1. From the [SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) running in terminal 1, set the setting that enables auto-rehoming. You must issue this setting before creating the `REGIONAL BY ROW` tables that you want auto-rehomed. @@ -2905,7 +2905,7 @@ ALTER TABLE {table} ALTER COLUMN crdb_region SET ON UPDATE rehome_row()::db.publ SET enable_auto_rehoming = on; ~~~ -1. In a second terminal window (call it _terminal 2_), [finish the tutorial starting from step 3]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#step-3-load-and-run-movr) onward to finish loading the cluster with data and applying the multi-region SQL configuration. +1. In a second terminal window (call it _terminal 2_), finish loading the cluster with data and applying the multi-region SQL configuration. 1. Switch back to terminal 1, and check the gateway region of the node you are currently connected to: diff --git a/src/current/v26.2/choosing-a-multi-region-configuration.md b/src/current/v26.2/choosing-a-multi-region-configuration.md index d31479987dc..1b48d1519fb 100644 --- a/src/current/v26.2/choosing-a-multi-region-configuration.md +++ b/src/current/v26.2/choosing-a-multi-region-configuration.md @@ -65,7 +65,6 @@ Different databases and tables within the same cluster can each use different co - [Survive Region Outages with CockroachDB](https://www.cockroachlabs.com/blog/under-the-hood-multi-region/) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.2/cluster-setup-troubleshooting.md b/src/current/v26.2/cluster-setup-troubleshooting.md index e7c16577c14..d952f1af609 100644 --- a/src/current/v26.2/cluster-setup-troubleshooting.md +++ b/src/current/v26.2/cluster-setup-troubleshooting.md @@ -91,7 +91,7 @@ You should see a list of the built-in databases: If you’re not seeing the output above, check for the following: - `connection refused` error, which indicates you have not included some flag that you used to start the node. We have additional troubleshooting steps for this error [here]({% link {{ page.version.version }}/common-errors.md %}#connection-refused). -- The node crashed. To ascertain if the node crashed, run `ps | grep cockroach` to look for the `cockroach` process. If you cannot locate the `cockroach` process (i.e., it crashed), [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}), including the [logs from your node]({% link {{ page.version.version }}/configure-logs.md %}#logging-directory) and any errors you received. +- The node crashed. To ascertain if the node crashed, run `ps | grep cockroach` to look for the `cockroach` process. If you cannot locate the `cockroach` process (i.e., it crashed), file an issue in Github, including the [logs from your node]({% link {{ page.version.version }}/configure-logs.md %}#logging-directory) and any errors you received. ## Cannot run a multi-node CockroachDB cluster on the same machine @@ -526,7 +526,7 @@ CockroachDB memory usage has the following components: {% include {{ page.version.version }}/prod-deployment/healthy-crdb-memory.md %} - If you observe values not within the expected range for a healthy cluster, [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). + If you observe values not within the expected range for a healthy cluster, file an issue in Github. #### Out-of-memory (OOM) crash @@ -582,7 +582,7 @@ To identify under-replicated/unavailable ranges: 1. On the [**Cluster Overview** page]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}), check the **Replication Status**. If the **Under-replicated ranges** or **Unavailable ranges** count is non-zero, then you have under-replicated or unavailable ranges in your cluster. -1. Check for a network partition: On the [**Network** page]({% link {{ page.version.version }}/ui-network-latency-page.md %}), if there are nodes in the network matrix with [no connections]({% link {{ page.version.version }}/ui-network-latency-page.md %}#no-connections), this may indicate a network partition. If there is no partition and still no upreplication after 5 minutes, then [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). +1. Check for a network partition: On the [**Network** page]({% link {{ page.version.version }}/ui-network-latency-page.md %}), if there are nodes in the network matrix with [no connections]({% link {{ page.version.version }}/ui-network-latency-page.md %}#no-connections), this may indicate a network partition. If there is no partition and still no upreplication after 5 minutes, then file an issue in Github. **Add nodes to the cluster:** @@ -594,7 +594,7 @@ If you still see under-replicated/unavailable ranges on the Cluster Overview pag 1. On the [**Advanced Debug** page]({% link {{ page.version.version }}/ui-debug-pages.md %}), click **Problem Ranges**. 1. In the **Connections** table, identify the node with the under-replicated/unavailable ranges and click the node ID in the Node column. 1. To view the **Range Report** for a range, click on the range number in the **Under-replicated (or slow)** table or **Unavailable** table. -1. On the Range Report page, scroll down to the **Simulated Allocator Output** section. The table contains an error message which explains the reason for the under-replicated range. Follow the guidance in the message to resolve the issue. If you need help understanding the error or the guidance, [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). Please be sure to include the full Range Report and error message when you submit the issue. +1. On the Range Report page, scroll down to the **Simulated Allocator Output** section. The table contains an error message which explains the reason for the under-replicated range. Follow the guidance in the message to resolve the issue. If you need help understanding the error or the guidance, file an issue in Github. Please be sure to include the full Range Report and error message when you submit the issue. #### Check for under-replicated or unavailable data diff --git a/src/current/v26.2/cockroach-debug-encryption-active-key.md b/src/current/v26.2/cockroach-debug-encryption-active-key.md index 7c1ddf7988e..80f43344ed9 100644 --- a/src/current/v26.2/cockroach-debug-encryption-active-key.md +++ b/src/current/v26.2/cockroach-debug-encryption-active-key.md @@ -40,6 +40,5 @@ AES128_CTR:be235c29239aa84a48e5e1874d76aebf7fb3c1bdc438cec2eb98de82f06a57a0 ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.2/cockroach-debug-encryption-decrypt.md b/src/current/v26.2/cockroach-debug-encryption-decrypt.md index 94b88d85ba0..10b10c90ec2 100644 --- a/src/current/v26.2/cockroach-debug-encryption-decrypt.md +++ b/src/current/v26.2/cockroach-debug-encryption-decrypt.md @@ -57,7 +57,6 @@ The `cockroach debug encryption-decrypt` command will output the decrypted store ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) diff --git a/src/current/v26.2/cockroach-debug-job-trace.md b/src/current/v26.2/cockroach-debug-job-trace.md index 0684f385172..eb0047826b6 100644 --- a/src/current/v26.2/cockroach-debug-job-trace.md +++ b/src/current/v26.2/cockroach-debug-job-trace.md @@ -70,7 +70,6 @@ You will find the zip file in the directory you ran the command from: ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) diff --git a/src/current/v26.2/cockroach-debug-merge-logs.md b/src/current/v26.2/cockroach-debug-merge-logs.md index 4ebed81dd51..8dd6c4ecd23 100644 --- a/src/current/v26.2/cockroach-debug-merge-logs.md +++ b/src/current/v26.2/cockroach-debug-merge-logs.md @@ -84,6 +84,5 @@ As of v23.2, logs can be configured to use a [timezone with formats `crdb-v1` or ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.2/cockroach-debug-tsdump.md b/src/current/v26.2/cockroach-debug-tsdump.md index a34784aef86..271855498e8 100644 --- a/src/current/v26.2/cockroach-debug-tsdump.md +++ b/src/current/v26.2/cockroach-debug-tsdump.md @@ -183,6 +183,5 @@ $ cockroach debug tsdump --format=raw --metrics-list-file=metrics.txt --certs-di ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.2/cockroach-debug-zip.md b/src/current/v26.2/cockroach-debug-zip.md index 364ce9fc4ce..7c86e0071bb 100644 --- a/src/current/v26.2/cockroach-debug-zip.md +++ b/src/current/v26.2/cockroach-debug-zip.md @@ -286,6 +286,5 @@ cockroach debug zip ./cockroach-data/logs/debug.zip --redact --insecure --host=2 ## See also -- [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) - [Troubleshooting Overview]({% link {{ page.version.version }}/troubleshooting-overview.md %}) diff --git a/src/current/v26.2/cockroach-demo.md b/src/current/v26.2/cockroach-demo.md index 029d2f0c252..47257c7f236 100644 --- a/src/current/v26.2/cockroach-demo.md +++ b/src/current/v26.2/cockroach-demo.md @@ -489,8 +489,6 @@ This command starts a 9-node demo cluster with the `movr` database preloaded and The `--global` flag is an experimental feature of `cockroach demo`. The interface and output are subject to change. {{site.data.alerts.end}} -For a tutorial that uses a demo cluster to demonstrate CockroachDB's multi-region capabilities, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ### Add, shut down, and restart nodes in a multi-node demo cluster In a multi-node demo cluster, you can use `\demo` [shell commands](#commands) to add, shut down, restart, decommission, and recommission individual nodes. diff --git a/src/current/v26.2/cockroach-start.md b/src/current/v26.2/cockroach-start.md index 831f0a9e449..89e6e23c4c0 100644 --- a/src/current/v26.2/cockroach-start.md +++ b/src/current/v26.2/cockroach-start.md @@ -449,7 +449,7 @@ $ cockroach init \ ### Start a multi-region cluster -In this example we will start a multi-node [local cluster]({% link {{ page.version.version }}/start-a-local-cluster.md %}) with a multi-region setup that uses the same regions (passed to the [`--locality`](#locality) flag) as the [multi-region MovR demo application]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +In this example we will start a multi-node [local cluster]({% link {{ page.version.version }}/start-a-local-cluster.md %}) with a multi-region setup that uses the same regions (passed to the [`--locality`](#locality) flag) as the multi-region MovR demo application. 1. Start a node in the `us-east1` region: @@ -518,8 +518,6 @@ In this example we will start a multi-node [local cluster]({% link {{ page.versi For more information about running CockroachDB multi-region, see the [Multi-region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). -For a more advanced example showing how to run a simulated workload on a multi-region CockroachDB cluster on your local machine, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - {{site.data.alerts.callout_info}} For more information about the `--locality` flag, see [Locality](#locality). {{site.data.alerts.end}} diff --git a/src/current/v26.2/cockroach-workload.md b/src/current/v26.2/cockroach-workload.md index 439d4b7f423..6ad72918b82 100644 --- a/src/current/v26.2/cockroach-workload.md +++ b/src/current/v26.2/cockroach-workload.md @@ -674,4 +674,3 @@ To customize the frequency of per-operation statistics, use the `--display-every - [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) - [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %}) -- [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-small.md %}) diff --git a/src/current/v26.2/data-domiciling.md b/src/current/v26.2/data-domiciling.md index fa3af83438e..2c9c66e013e 100644 --- a/src/current/v26.2/data-domiciling.md +++ b/src/current/v26.2/data-domiciling.md @@ -138,7 +138,7 @@ ALTER DATABASE movr ADD REGION "us-west1"; Next, check the [critical nodes status endpoint](monitoring-and-alerting.html#critical-nodes-endpoint) to see which ranges are still not in compliance with your desired domiciling: that data on EU-based entities (users, etc.) does not leave EU-based nodes. -On a small demo cluster like this one, the data movement from the previous step should finish quickly; on larger clusters, the rebalancing process may take longer. For more information about the performance considerations of rebalancing data in multi-region clusters, see [Performance considerations](migrate-to-multiregion-sql.html#performance-considerations). +On a small demo cluster like this one, the data movement from the previous step should finish quickly; on larger clusters, the rebalancing process may take longer. With the default settings, you should expect some replicas in the cluster to be violating this constraint. Those replicas will appear in the `violatingConstraints` field of the output. @@ -436,9 +436,7 @@ Using CockroachDB as part of your approach to data domiciling has several limita ## See also - [How to Choose a Multi-region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Multi-Region Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) - [Reads and Writes in CockroachDB]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}) - [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) diff --git a/src/current/v26.2/demo-low-latency-multi-region-deployment.md b/src/current/v26.2/demo-low-latency-multi-region-deployment.md deleted file mode 100644 index 9b49ef35c12..00000000000 --- a/src/current/v26.2/demo-low-latency-multi-region-deployment.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Low Latency Reads and Writes in a Multi-Region Cluster -summary: Use data topologies to get low-latency reads and writes in a multi-region CockroachDB cluster. -toc: true -toc_not_nested: true -key: demo-geo-partitioning.html -docs_area: ---- - -CockroachDB multi-region capabilities make it easier to run global applications. For an overview of these capabilities, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -In multi-region clusters, the distribution of data becomes a performance consideration. This makes it important to think about the [survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) of each database. Then, for each table in the database, use the right [table locality]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) to locate data for optimal performance. - -In this tutorial, you will: - -1. Simulate a multi-region CockroachDB cluster on your local machine. -1. Run a workload on the cluster using our fictional vehicle-sharing application called [MovR]({% link {{ page.version.version }}/movr.md %}). -1. See the effects of network latency on SQL query performance in the default (non-multi-region) configuration. -1. Configure the cluster for good multi-region performance by issuing SQL statements that choose the right [survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) and [table localities]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality). - -## Considerations - -This page describes a demo cluster; it does not show best practices for a production deployment. For more information about production deployments of multi-region applications, see [Orchestrate CockroachDB Across Multiple Kubernetes Clusters]({% link {{ page.version.version }}/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md %}) and the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). - -Because the instructions on this page describe how to simulate a multi-region cluster on a single machine, the absolute performance numbers described below are not reflective of [the performance you can expect of single-point reads and writes against CockroachDB in a production setting]({% link {{ page.version.version }}/frequently-asked-questions.md %}#single-row-perf). Instead, the instructions are designed with the following goals: - -- To show the _relative_ magnitude of the performance improvements to expect when you configure a multi-region cluster correctly. -- To be as easy to try as possible with minimal configuration and setup. - -## Before you begin - -Make sure you have: - -- [A basic understanding of the MovR application](#a-basic-understanding-of-the-movr-application) -- [Docker](https://www.docker.com) installed on the local machine - -### A basic understanding of the MovR application - -The workload you'll run against the cluster is our open-source, fictional, peer-to-peer vehicle-sharing app, [MovR]({% link {{ page.version.version }}/movr.md %}). Each instance represents users in a specific region: - -- `europe-west1`, covering the cities of Amsterdam, Paris, and Rome. -- `us-east1`, covering the cities of New York, Boston, and Washington, D.C. -- `us-west1`, covering the cities of Los Angeles, San Francisco, and Seattle. - -#### The MovR schema - -{% include {{ page.version.version }}/misc/movr-schema.md %} - -All of the tables except `promo_codes` have a composite primary key of `city` and `id`, in that order. This means that the rows in these tables are ordered by their geography. These tables are read from and written to very frequently. To keep read and write latency low, you'll use the [`REGIONAL BY ROW` table locality pattern]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) for these tables. - -The data in the `promo_codes` table is different: it is not tied to geography, and it is rarely updated. This type of table is often referred to as a "reference table" or "lookup table". In this case, you'll use the [Global table locality pattern]({% link {{ page.version.version }}/table-localities.md %}#global-tables) to keep read latencies low. - -For a description of the sequence of SQL statements issued by the MovR application in response to user actions, see [How the MovR application works]({% link {{ page.version.version }}/movr.md %}#how-the-movr-application-works). - -## Step 1. Simulate a multi-region cluster - -{% include {{page.version.version}}/sql/start-a-multi-region-demo-cluster.md %} - -To verify that the simulated latencies are working as expected, check the [Network Latency Page]({% link {{ page.version.version }}/ui-network-latency-page.md %}) in the DB Console. Round trip times between `us-west1` and `europe-west1` should be in the 150 ms range. - -## Step 2. Determine node locations - -To determine which nodes are in which regions, you will need to refer to two (2) things: - -1. The output of the `\demo ls` from the SQL shell, which shows the TCP ports on the local machine that we will connect to from the MovR application. -1. The node IDs shown on the **Network Latency Page**. - -Here is the output of `\demo ls` from the SQL shell. - -{% include_cached copy-clipboard.html %} -~~~ -> \demo ls -~~~ - -~~~ -node 1: - (webui) http://127.0.0.1:8080/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26257?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257 - -node 2: - (webui) http://127.0.0.1:8081/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26258?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26258 - -node 3: - (webui) http://127.0.0.1:8082/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26259?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26259 - -node 4: - (webui) http://127.0.0.1:8083/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26260?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26260 - -node 5: - (webui) http://127.0.0.1:8084/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26261?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26261 - -node 6: - (webui) http://127.0.0.1:8085/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26262?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26262 - -node 7: - (webui) http://127.0.0.1:8086/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26263?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26263 - -node 8: - (webui) http://127.0.0.1:8087/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26264?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26264 - -node 9: - (webui) http://127.0.0.1:8088/demologin?password=demo76950&username=demo - (sql) postgres://demo:demo76950@127.0.0.1:26265?sslmode=require - (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26265 -~~~ - -And here is the view on the **Network Latency Page**, which shows which nodes are in which cluster regions: - -Geo-partitioning network latency - -You can see by referring back and forth between `\demo ls` and the **Network Latency Page** that the cluster has the following region/node/port correspondences, which we can use to determine how to connect MovR from various regions: - -| Node ID | Region | Port on localhost | -|---------+--------------+-------------------| -| N2 | europe-west1 | 26263 | -| N5 | europe-west1 | 26264 | -| N7 | europe-west1 | 26265 | -| N4 | us-west1 | 26262 | -| N6 | us-west1 | 26260 | -| N9 | us-west1 | 26261 | -| N1 | us-east1 | 26257 | -| N3 | us-east1 | 26259 | -| N8 | us-east1 | 26258 | - -## Step 3. Load and run MovR - -Follow these steps to start 3 instances of MovR. Each instance is pointed at a node in a different region. This will simulate load from that region. - -1. In the SQL shell, create the `movr` database: - - {% include_cached copy-clipboard.html %} - ~~~ sql - CREATE DATABASE IF NOT EXISTS movr; - ~~~ - -1. Open a second terminal and run the command below to populate the MovR data set. The options are mostly self-explanatory. We limit the application to 1 thread because using multiple threads quickly overloads this small demo cluster's ability to ingest data. As a result, loading the data takes about 90 seconds on a fast laptop. - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-load" \ - --url "postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable" \ - --num-threads 1 \ - load \ - --num-users 100 \ - --num-rides 100 \ - --num-vehicles 10 \ - --city "boston" \ - --city "new york" \ - --city "washington dc" \ - --city="amsterdam" \ - --city="paris" \ - --city="rome" \ - --city="los angeles" \ - --city="san francisco" \ - --city="seattle" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable - [INFO] (MainThread) Loading single region MovR - [INFO] (MainThread) initializing tables - [INFO] (MainThread) loading cities ['boston', 'new york', 'washington dc', 'amsterdam', 'paris', 'rome', 'los angeles', 'san francisco', 'seattle'] - [INFO] (MainThread) loading movr data with ~100 users, ~10 vehicles, ~100 rides, ~1000 histories, and ~1000 promo codes - [INFO] (Thread-1 ) Generating user data for boston... - ... output snipped ... - [INFO] (Thread-1 ) Generating 1000 promo codes... - [INFO] (MainThread) populated 9 cities in 86.986230 seconds - ~~~ - -1. In the same terminal window, run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-us-east" \ - --url "postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable" \ - run \ - --city="boston" \ - --city="new york" \ - --city="washington dc" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26257/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['boston', 'new york', 'washington dc'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ... - ~~~ - -1. Open a third terminal and run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-us-west" \ - --url "postgres://root@docker.for.mac.localhost:26260/movr?sslmode=disable" \ - run \ - --city="los angeles" \ - --city="san francisco" \ - --city="seattle" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26260/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['los angeles', 'san francisco', 'seattle'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ~~~ - -1. Open a fourth terminal and run the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - docker run -it --rm cockroachdb/movr:20.11.1 \ - --app-name "movr-eu-west" \ - --url "postgres://root@docker.for.mac.localhost:26264/movr?sslmode=disable" \ - run \ - --city="amsterdam" \ - --city="paris" \ - --city="rome" - ~~~ - - ~~~ - [INFO] (MainThread) connected to movr database @ postgres://root@docker.for.mac.localhost:26264/movr?sslmode=disable - [INFO] (MainThread) simulating movr load for cities ['amsterdam', 'paris', 'rome'] - [INFO] (MainThread) warming up.... - [INFO] (MainThread) running single region queries... - ... - ~~~ - -## Step 4. Check service latency - -Now that you have load hitting the cluster from different regions, check how the service latencies look before you do any multi-region configuration from SQL. This is the "before" case in the "before and after". - -In the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) at http://127.0.0.1:8080, click [**Metrics**]({% link {{ page.version.version }}/ui-overview-dashboard.md %}) on the left and hover over the [**Service Latency: SQL, 99th percentile**]({% link {{ page.version.version }}/ui-overview-dashboard.md %}#service-latency-sql-99th-percentile) timeseries graph. You should see the effects of network latency on this workload. - -Geo-partitioning SQL latency - -For each of the 3 nodes that you are pointing the movr workload at, the max latency of 99% of queries are in the 1-2 seconds range. The SQL latency is high because of the network latency between regions. - -To see the network latency between any two nodes in the cluster, click [**Network Latency**]({% link {{ page.version.version }}/ui-network-latency-page.md %}) in the left-hand navigation. - -Geo-partitioning network latency - -Within a single region, round-trip latency is under 6 ms (milliseconds). Across regions, round-trip latency is significantly higher. - -For example: - -- Round-trip latency between **N2** in `europe-west1` and **N3** in `us-east1` is 87 ms. -- Round-trip latency between **N2** in `europe-west1` and **N4** in `us-west1` is 196 ms. - -## Step 5. Execute multi-region SQL statements - -The following SQL statements will configure: - -- [The database's available regions](#configure-database-regions). -- [Which data should be optimized for access from which region](#configure-table-localities). - -This information is necessary so that CockroachDB can move data around to optimize access to particular data from particular regions. The main focus is reducing latency in a global deployment. For more information about how this works at a high level, see the [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -{{site.data.alerts.callout_info}} -The following `ALTER` statements will take some seconds to run, since the cluster is under load. -{{site.data.alerts.end}} - -### Configure database regions - -Back in the SQL shell, switch to the `movr` database: - -{% include_cached copy-clipboard.html %} -~~~ sql -USE movr; -~~~ - -{% include {{page.version.version}}/sql/multiregion-movr-add-regions.md %} - -### Configure table localities - -#### Configure GLOBAL tables - -As mentioned earlier, all of the tables except `promo_codes` are geographically specific. - -{% include {{page.version.version}}/sql/multiregion-movr-global.md %} - -#### Configure REGIONAL BY ROW tables - -{% include {{page.version.version}}/sql/multiregion-movr-regional-by-row.md %} - -## Step 6. Re-check service latency - -As the multi-region schema changes complete, you should see changes to the following metrics: - -- **SQL Queries**: This number should go up, since the cluster can service more load due to better performance (due to better data locality and lower latency). In this particular run, **the QPS has almost doubled, from 87 to 164**. -- **Service Latency: SQL, 99th percentile**: In general, even on a small demo cluster like this, the P99 latency should drop and also get less spiky over time, as schema changes finish and data is moved around. For this particular run, **the P99 latency has dropped from ~1200 ms to ~870 ms, an over 25% improvement**. -- **Replicas per Node**: This will increase, since the data needs to be spread across more nodes in order to service the multi-region workload appropriately. There is nothing you need to do about this, except to note that it happens, and is required for CockroachDB's improved multi-region performance features to work. - -{{site.data.alerts.callout_info}} -The small demo cluster used in this example is essentially in a state of overload from the start. The performance numbers shown here only reflect the direction of the performance improvements. You should expect to see much better absolute performance numbers than those described here [in a production deployment]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -Geo-partitioning SQL latency - -## See also - -- [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) -- [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) -- [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) -- [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) -- [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) -- [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) -- [Reads and Writes in CockroachDB]({% link {{ page.version.version }}/architecture/reads-and-writes-overview.md %}) -- [Install CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}) diff --git a/src/current/v26.2/file-an-issue.md b/src/current/v26.2/file-an-issue.md deleted file mode 100644 index 9255e2c08b2..00000000000 --- a/src/current/v26.2/file-an-issue.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: File an Issue -summary: Learn how to file a GitHub issue with CockroachDB. -toc: false -docs_area: manage ---- - -If you've tried to [troubleshoot]({% link {{ page.version.version }}/troubleshooting-overview.md %}) an issue yourself, have [reached out for help]({% link {{ page.version.version }}/support-resources.md %}), and are still stumped, you can file an issue in GitHub. - -To file an issue in GitHub, we need the following information: - -1. A summary of the issue. - -1. The steps to reproduce the issue. - -1. The result you expected. - -1. The result that actually occurred. - -1. The first few lines of the log file from each node in the cluster in a timeframe as close as possible to reproducing the issue. On most Unix-based systems running with defaults, you can get this information using the following command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ grep -F '[config]' cockroach-data/logs/cockroach.log - ~~~ - {{site.data.alerts.callout_info}}You might need to replace cockroach-data/logs with the location of your logs.{{site.data.alerts.end}} - If the logs are not available, include the output of `cockroach version` for each node in the cluster. - -### Template - -You can use this as a template for [filing an issue in GitHub](https://github.com/cockroachdb/cockroach/issues/new): - -~~~ - -## Summary - - - -## Steps to reproduce - -1. -2. -3. - -## Expected Result - - - -## Actual Result - - - -## Log files/version - -### Node 1 - - - -### Node 2 - - - -### Node 3 - - - -~~~ diff --git a/src/current/v26.2/frequently-asked-questions.md b/src/current/v26.2/frequently-asked-questions.md index 2bac8e0ffe6..bc28ed89750 100644 --- a/src/current/v26.2/frequently-asked-questions.md +++ b/src/current/v26.2/frequently-asked-questions.md @@ -68,7 +68,7 @@ CockroachDB replicates your data for availability and guarantees consistency bet - Different servers on different racks within a datacenter to tolerate rack power/network failures - Different servers in different datacenters to tolerate large scale network or power outages -In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to locate data for optimal performance and resiliency. For a step-by-step demonstration, see [Low Latency Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +In a CockroachDB cluster spread across multiple geographic regions, the round-trip latency between regions will have a direct effect on your database's performance. In such cases, it is important to think about the latency requirements of each table and then use the appropriate [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to locate data for optimal performance and resiliency. **Automated Repair** diff --git a/src/current/v26.2/global-tables.md b/src/current/v26.2/global-tables.md index ffd7928a817..202309cf20c 100644 --- a/src/current/v26.2/global-tables.md +++ b/src/current/v26.2/global-tables.md @@ -61,7 +61,7 @@ To use this pattern, set the [table locality]({% link {{ page.version.version }} ~~~ {{site.data.alerts.callout_success}} -A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. For a tutorial showing how table localities can improve performance metrics across a multi-region cluster, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. {{site.data.alerts.end}} ## Characteristics @@ -96,10 +96,6 @@ The value of `kv.closed_timestamp.lead_for_global_reads_override` will impact wr - If rows in the table, and all latency-sensitive queries, can be tied to specific geographies, consider the [`REGIONAL` Table Locality Pattern]({% link {{ page.version.version }}/regional-tables.md %}) pattern. -## Tutorial - -For a step-by-step demonstration showing how CockroachDB's multi-region capabilities (including `GLOBAL` and `REGIONAL` tables) give you low-latency reads in a distributed cluster, see the tutorial on [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## See also {% include {{ page.version.version }}/topology-patterns/see-also.md %} diff --git a/src/current/v26.2/index.md b/src/current/v26.2/index.md index 5c612ce3c0d..ee5277a0a6a 100644 --- a/src/current/v26.2/index.md +++ b/src/current/v26.2/index.md @@ -79,7 +79,6 @@ docs_area:
  • Production Checklist
  • CockroachDB Cloud Deployment
  • Kubernetes Overview
    • -
  • Performance Profiles
  • Cluster Maintenance
    • diff --git a/src/current/v26.2/local-testing.md b/src/current/v26.2/local-testing.md index 871c4d77d11..f56c15a3fed 100644 --- a/src/current/v26.2/local-testing.md +++ b/src/current/v26.2/local-testing.md @@ -49,7 +49,7 @@ ALTER DATABASE system CONFIGURE ZONE USING "gc.ttlseconds" = 600; ~~~ {{site.data.alerts.callout_danger}} -These settings **are not** recommended for [performance benchmarking of CockroachDB]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-local.md %}) since they will lead to inaccurate results. +These settings **are not** recommended for performance benchmarking of CockroachDB since they will lead to inaccurate results. {{site.data.alerts.end}} ## Scope tests to a database when possible diff --git a/src/current/v26.2/migrate-to-multiregion-sql.md b/src/current/v26.2/migrate-to-multiregion-sql.md deleted file mode 100644 index 54e665eefdb..00000000000 --- a/src/current/v26.2/migrate-to-multiregion-sql.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Migrate to Multi-Region SQL -summary: Learn how to migrate to CockroachDB multi-region SQL user features. -toc: true -docs_area: deploy ---- - -This page describes how to migrate a multi-region cluster from using replication zones to using multi-region SQL abstractions. - -## Overview - -{{site.data.alerts.callout_info}} -If you are already using [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) to control your multi-region cluster, you can ignore this page. -{{site.data.alerts.end}} - -CockroachDB v21.1 added support for [improved multi-region capabilities that make it easier to run global applications]({% link {{ page.version.version }}/multiregion-overview.md %}). Using high-level SQL statements, you can control where your data is stored and how it is accessed to provide good performance and tunable latency for your application's users. - -Prior to v21.1, the only way to accomplish these goals in a multi-region cluster involved using lower-level mechanisms called [replication zones]({% link {{ page.version.version }}/configure-replication-zones.md %}) in specific patterns called _Duplicate indexes_, _Geo-partitioned replicas_, and _Geo-partitioned leaseholders_. - -These patterns and the use of replication zones are still fully supported. However, for most users, they are harder to use and in some cases can result in worse performance than the multi-region SQL abstractions. - -This page discusses: - -- Mappings from each of the legacy replication-zone-based patterns to the 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 underlying zone configuration changes that result from running the multi-region SQL statements. - -## Replication zone patterns and multi-region SQL abstractions - -{% include {{page.version.version}}/sql/replication-zone-patterns-to-multiregion-sql-mapping.md %} - -{{site.data.alerts.callout_info}} -CockroachDB will no longer provide the [Follow-the-Workload]({% link {{ page.version.version }}/topology-follow-the-workload.md %}) pattern's behavior for a database if you use the [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) with that database. In other words, the multi-region SQL statements do not provide a behavior that is analogous to Follow-the-Workload. -{{site.data.alerts.end}} - -For more information about how to use `ZONE` vs. `REGION` survival goals, see [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -For more information about when to use `GLOBAL` vs. `REGIONAL` tables, see [When to `Use` `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/table-localities.md %}#when-to-use-regional-vs-global-tables). - -## How to migrate a database to the multi-region SQL abstractions - -The following instructions assume that you will re-use your existing [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions) (that is, regions added during cluster setup using [`cockroach start --locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality)). - -### Performance considerations - -Expect performance to be temporarily affected by this process. When you run the commands described below, the cluster may need to do a significant amount of work to meet the new replica placement constraints it has just been given. Therefore, we recommend running this procedure at a time when you would normally perform scheduled maintenance. - -Depending on how long you are willing to wait between steps for the replica rebalancing process to settle down, data movement may still be occurring when the next set of constraints is added using the multi-region SQL abstractions; this may lead to further data movement. - -In other words, the process described here may result in a significant increase in CPU usage, IOPS, and network traffic while the cluster rebalances replicas to meet the final set of constraints you have provided it with. Until this process completes, the cluster may not be able to handle its normal workload. - -Note that the process of dropping the old zone configs that occurs when the old configurations are removed **must be complete** before you can [add regions to the database]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) and set [table localities]({% link {{ page.version.version }}/alter-table.md %}#set-locality). You can ensure this process is complete by waiting for the [`ALTER DATABASE ... CONFIGURE ZONE DISCARD`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement shown below to finish successfully. - -For a tutorial that shows how to transition a database to using multi-region SQL statements, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - -{{site.data.alerts.callout_info}} -As part of this migration, data may move temporarily out of the geography where you have constrained it to be placed. For more information about CockroachDB's support for data domiciling, see [Data Domiciling with CockroachDB]({% link {{ page.version.version }}/data-domiciling.md %}). -{{site.data.alerts.end}} - -### Step 1. Remove the old replication zone configurations - -Depending on which [legacy multi-region topology pattern]({% link {{ page.version.version }}/topology-patterns.md %}#multi-region) you are migrating from, the procedure will vary. For instructions showing how to remove the existing zone configuration for each pattern, see below. - -- [Duplicate indexes](#duplicate-indexes) -- [Geo-partitioned leaseholders](#geo-partitioned-leaseholders) -- [Geo-partitioned replicas](#geo-partitioned-replicas) - -{{site.data.alerts.callout_success}} -You can check the state of any schema object's replication zone configuration at any time using [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}). -{{site.data.alerts.end}} - -#### Duplicate indexes - -If you used the duplicate indexes pattern, the steps for backing out the old configuration are: - -1. Remove the replication zone configurations you added using the [`ALTER DATABASE ... CONFIGURE ZONE DISCARD`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement. Note that this will remove all zone configurations from the table. If you had any additional customizations beyond what are required for the duplicate indexes pattern, you will have to reapply them. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE postal_codes CONFIGURE ZONE DISCARD; - ~~~ - -1. Drop the extra indexes you added. This will have the side effect of also deleting the zone configurations you added to those indexes. - - {% include_cached copy-clipboard.html %} - ~~~ sql - DROP INDEX postal_codes@idx_central; - DROP INDEX postal_codes@idx_east; - ~~~ - -The latency and resiliency benefits of the duplicate indexes pattern can be replaced by making `postal_codes` a [`GLOBAL` table]({% link {{ page.version.version }}/global-tables.md %}) with a [survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) that meets your needs. - -#### Geo-partitioned replicas - -If you applied the geo-partitioned replicas pattern, the steps for backing out the old configuration are: - -1. Remove the manually created table partition. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE users PARTITION BY NOTHING; - ~~~ - -1. Remove the manually created partition on the secondary indexes. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER INDEX users_last_name_index PARTITION BY NOTHING; - ~~~ - -The latency and resiliency benefits of the geo-partitioned replicas pattern can be replaced by making `users` a [`REGIONAL BY ROW` table]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -{{site.data.alerts.callout_info}} -The multi-region SQL abstractions use a hidden [`crdb_region`]({% link {{ page.version.version }}/alter-table.md %}#set-locality) column to represent the row's home region. You may need to modify your existing schema to take this into account. For example, if you already have a column you are using to denote each row's home region, you can use that name instead of `crdb_region` by following the instructions on the [`ALTER TABLE ... SET LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#set-locality) page. -{{site.data.alerts.end}} - -#### Geo-partitioned leaseholders - -If you applied the geo-partitioned leaseholders pattern, the steps for backing out the old configuration are: - -1. Remove the manually created table partition. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER TABLE users PARTITION BY NOTHING; - ~~~ - -1. Remove the manually created partition on the secondary indexes. This will also automatically remove the replication zone configurations that were applied to the partition as part of the instructions. - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER INDEX users_last_name_index PARTITION BY NOTHING; - ~~~ - -The latency and resiliency benefits of the geo-partitioned leaseholders pattern can be replaced by making `users` a [`REGIONAL BY ROW` table]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 2. Add a primary region to your database - -The steps from this point forward assume that you have cleared your prior replication zone configurations and will be using the [multi-region SQL abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}) to work with a cluster that has existing [cluster regions]({% link {{ page.version.version }}/multiregion-overview.md %}#cluster-regions). - -Every multi-region database needs to have a primary region. To set the primary region, issue the [ALTER DATABASE ... SET PRIMARY REGION]({% link {{ page.version.version }}/alter-database.md %}#set-primary-region) statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo SET PRIMARY REGION = "us-west1" -~~~ - -### Step 3. Add more regions to the database - -To add another region to the database, issue the [`ADD REGION`]({% link {{ page.version.version }}/alter-database.md %}#add-region) statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo ADD REGION "us-central1"; -~~~ - -### Step 4. (Optional) Configure your database survival goal - -Depending on your desired database [survival goal]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals), you can choose from the following settings: - -- [`ZONE` survival]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) (Default): the database will remain fully available for reads and writes if one zone in a region goes down. More than one zone going down concurrently may affect availability. -- [`REGION` survival]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals): the database will remain fully available for reads and writes if one region goes down. More than one region going down concurrently may affect availability. - -For example, to set a region survival goal, issue the following SQL statement: - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER DATABASE foo SURVIVE REGION FAILURE; -~~~ - -For more information about when to use `ZONE` vs. `REGION` survival goals, see [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 5. Configure table localities - -For each table in your database, apply the [table locality]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) that provides the latency and resiliency requirements you need for that table. - -As described in [Replication zone patterns and multi-region SQL abstractions](#replication-zone-patterns-and-multi-region-sql-abstractions), the mapping from legacy replication zone patterns to multi-region SQL abstractions is: - -{% include {{page.version.version}}/sql/replication-zone-patterns-to-multiregion-sql-mapping.md %} - -For example, to configure the `postal_codes` table from the [duplicate indexes example](#duplicate-indexes) to use [multi-region SQL]({% link {{ page.version.version }}/multiregion-overview.md %}), you would enter the following statements to make the `postal_codes` table a [`GLOBAL` table]({% link {{ page.version.version }}/global-tables.md %}): - -{% include_cached copy-clipboard.html %} -~~~ sql -ALTER TABLE postal_codes SET LOCALITY GLOBAL; -~~~ - -For more information about when to use `GLOBAL` vs. `REGIONAL` tables, see [When to Use `REGIONAL` vs. `GLOBAL` Tables]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals). - -### Step 6. (Optional) View the updated zone configurations - -The multi-region SQL statements operate on the same replication zone configurations that you have access to via the [`ALTER TABLE ... CONFIGURE ZONE`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) statement. If you are interested in seeing how they work with the lower-level zone config mechanisms, you can use the [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}) statement to view the zone configurations. - -For example, given a multi-region demo cluster set up using the instructions in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), here is what the zone configs for several tables in the [MovR schema]({% link {{ page.version.version }}/movr.md %}) look like. - -#### Regional by row tables - -A [`REGIONAL BY ROW`]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) table differs from the default by setting the following zone configuration settings: - -- [`num_replicas`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_replicas) -- [`num_voters`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_voters) -- [`constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#constraints) -- [`voter_constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#voter_constraints) -- [`lease_preferences`]({% link {{ page.version.version }}/configure-replication-zones.md %}#lease_preferences) - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE users; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------------------------------------------------------- - DATABASE movr | ALTER DATABASE movr CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 5, - | num_voters = 3, - | constraints = '{+region=europe-west1: 1, +region=us-east1: 1, +region=us-west1: 1}', - | voter_constraints = '[+region=us-east1]', - | lease_preferences = '[[+region=us-east1]]' -(1 row) -~~~ - -The same table, loaded in a demo cluster with no zone configuration changes, looks like this: - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE users; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------- - RANGE default | ALTER RANGE default CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 3, - | constraints = '[]', - | lease_preferences = '[]' -(1 row) - -~~~ - -{{site.data.alerts.callout_danger}} -{% include {{page.version.version}}/known-limitations/secondary-regions-with-regional-by-row-tables.md %} -{{site.data.alerts.end}} - -#### Global tables - -A [`GLOBAL`]({% link {{ page.version.version }}/table-localities.md %}) table differs from the default by setting the following zone configuration settings: - -- [`global_reads`]({% link {{ page.version.version }}/configure-replication-zones.md %}#global_reads) -- [`num_replicas`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_replicas) -- [`num_voters`]({% link {{ page.version.version }}/configure-replication-zones.md %}#num_voters) -- [`constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#constraints) -- [`voter_constraints`]({% link {{ page.version.version }}/configure-replication-zones.md %}#voter_constraints) -- [`lease_preferences`]({% link {{ page.version.version }}/configure-replication-zones.md %}#lease_preferences) - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE promo_codes; -~~~ - -~~~ - target | raw_config_sql ---------------------+------------------------------------------------------------------------------------------- - TABLE promo_codes | ALTER TABLE promo_codes CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | global_reads = true, - | num_replicas = 5, - | num_voters = 3, - | constraints = '{+region=europe-west1: 1, +region=us-east1: 1, +region=us-west1: 1}', - | voter_constraints = '[+region=us-east1]', - | lease_preferences = '[[+region=us-east1]]' -(1 row) -~~~ - -The same table, loaded in a demo cluster with no zone configuration changes, looks like this: - -{% include_cached copy-clipboard.html %} -~~~ sql -SHOW ZONE CONFIGURATION FROM TABLE promo_codes; -~~~ - -~~~ - target | raw_config_sql -----------------+------------------------------------------- - RANGE default | ALTER RANGE default CONFIGURE ZONE USING - | range_min_bytes = 134217728, - | range_max_bytes = 536870912, - | gc.ttlseconds = 90000, - | num_replicas = 3, - | constraints = '[]', - | lease_preferences = '[]' -(1 row) -~~~ - -## See also - -- [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [When to use zone vs. region survival goals]({% link {{ page.version.version }}/multiregion-overview.md %}#survival-goals) -- [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) -- [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Configure Replication Zones]({% link {{ page.version.version }}/configure-replication-zones.md %}) -- [Non-voting replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#non-voting-replicas) -- [Troubleshoot Replication Zones]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}) diff --git a/src/current/v26.2/movr.md b/src/current/v26.2/movr.md index 024525eceb2..718408229df 100644 --- a/src/current/v26.2/movr.md +++ b/src/current/v26.2/movr.md @@ -91,10 +91,6 @@ $ cockroach demo movr {% include {{ page.version.version }}/misc/movr-workflow.md %} -## Extended examples - -For a tutorial on running MovR against a multi-region cluster, using two important multi-region [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to get very low latency reads and writes, see [Low Latency, Multi-Region Deployment]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## See also - [Features in Preview]({% link {{ page.version.version }}/cockroachdb-feature-availability.md %}) diff --git a/src/current/v26.2/multiregion-overview.md b/src/current/v26.2/multiregion-overview.md index 93fa6a82721..7e01b78913a 100644 --- a/src/current/v26.2/multiregion-overview.md +++ b/src/current/v26.2/multiregion-overview.md @@ -178,8 +178,6 @@ For more information, see [Zone Config Extensions]({% link {{ page.version.versi - [Global Tables]({% link {{ page.version.version }}/global-tables.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`ALTER DATABASE ... DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) - [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) diff --git a/src/current/v26.2/multiregion-scale-application.md b/src/current/v26.2/multiregion-scale-application.md index 04f062e28b5..9963ec9b3ed 100644 --- a/src/current/v26.2/multiregion-scale-application.md +++ b/src/current/v26.2/multiregion-scale-application.md @@ -85,7 +85,7 @@ For most table localities, including the default locality `LOCALITY REGIONAL BY However, there are some scenarios in which you might need to update the SQL operations in your application. For example: -- If a table has a `REGIONAL BY ROW AS ` table locality, and you want to explicitly insert regional values into a table, as shown in [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}#configure-regional-by-row-tables). +- If a table has a `REGIONAL BY ROW AS ` table locality, and you want to explicitly insert regional values into a table. - If a table has a `REGIONAL BY ROW` locality, and you want to update the `crdb_region` value of existing rows in the table based on some other column value, as shown in [Set the table locality to `REGIONAL BY ROW`]({% link {{ page.version.version }}/alter-table.md %}#set-the-table-locality-to-regional-by-row). - If a table has a `REGIONAL BY ROW` locality, and you want to filter a [selection query]({% link {{ page.version.version }}/select-clause.md %}#filter-rows) based on the `crdb_region` value. @@ -147,4 +147,3 @@ In the absence of an explicit, back-filling computed column for the hidden `crdb ## See also - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) diff --git a/src/current/v26.2/multiregion-survival-goals.md b/src/current/v26.2/multiregion-survival-goals.md index b49ee8544dc..bffb3b9ba12 100644 --- a/src/current/v26.2/multiregion-survival-goals.md +++ b/src/current/v26.2/multiregion-survival-goals.md @@ -63,10 +63,8 @@ Set a [`REGION` survival goal]({% link {{ page.version.version }}/multiregion-su + [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) + [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [Table Localities]({% link {{ page.version.version }}/table-localities.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.2/performance-benchmarking-with-tpcc-large.md b/src/current/v26.2/performance-benchmarking-with-tpcc-large.md deleted file mode 100644 index c35ad1017b2..00000000000 --- a/src/current/v26.2/performance-benchmarking-with-tpcc-large.md +++ /dev/null @@ -1,456 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C with 81 nodes on `c5d.9xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-100k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- [Review TPC-C concepts](#review-tpc-c-concepts) -- [Request a trial license](#request-a-trial-license) - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -### Request a trial license - -Reproducing these TPC-C results involves using CockroachDB's [partitioning]({% link {{ page.version.version }}/partitioning.md %}) feature to ensure replicas for any given section of data are located on the same nodes that will be queried by the load generator for that section of data. Partitioning helps distribute the workload evenly across the cluster. - -The partitioning feature requires an Enterprise license, so [request a 30-day trial license](https://www.cockroachlabs.com/get-cockroachdb/enterprise/) before you get started. - -You should receive your trial license via email within a few minutes. You'll enable your license once your cluster is up-and-running. - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 86 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 81 for CockroachDB nodes and 5 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.9xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Start CockroachDB using the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 \ - --locality=rack=0 - ~~~ - - Each node will start with a [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) that includes an artificial "rack number" (e.g., `--locality=rack=0`). Use 81 racks for 81 nodes so that 1 node will be assigned to each rack. - -1. Repeat these steps for the other 80 VMs for CockroachDB nodes. Each time, be sure to: - - Adjust the `--advertise-addr` flag. - - Set the [`--locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality) flag to the appropriate "rack number". - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Configure the cluster - -You'll be importing a large TPC-C data set. To speed that up, you can temporarily disable replication and tweak some cluster settings. You'll also need to enable the Enterprise license you requested earlier. - -1. SSH to any VM with the `cockroach` binary. - -1. Launch the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=
    - ~~~ - -1. Adjust some [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ sql - SET CLUSTER SETTING kv.dist_sender.concurrency_limit = 2016; - SET CLUSTER SETTING kv.snapshot_rebalance.max_rate = '256 MiB'; - SET CLUSTER SETTING sql.stats.automatic_collection.enabled = false; - SET CLUSTER SETTING schemachanger.backfiller.max_buffer_size = '5 GiB'; - SET CLUSTER SETTING rocksdb.min_wal_sync_interval = '500us'; - SET CLUSTER SETTING kv.range_merge.queue_enabled = false - ~~~ - -1. Change the default [GC TTL]({% link {{ page.version.version }}/configure-replication-zones.md %}#gc-ttlseconds) to the following value: - - {% include_cached copy-clipboard.html %} - ~~~ sql - ALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 600; - ~~~ - -1. Enable the trial license you requested earlier: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING cluster.organization = ''; - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING enterprise.license = ''; - ~~~ - -1. Exit the SQL shell: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > \q - ~~~ - -## Step 4. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --replicate-static-columns \ - --partition-strategy=leases \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 11.2 TB of data for 140,000 "warehouses". This can take up to 8 hours to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 5. Partition the database - -1. [Partition your database]({% link {{ page.version.version }}/partitioning.md %}) to divide all of the TPC-C tables and indexes into 81 partitions, one per rack, and then use [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) to pin those partitions to a particular rack. - -1. Wait for up-replication and partitioning to finish. You will know when they have finished because both the number of *lease transfers* and *snapshots* will go down to `0` and stay there. This will likely take 10s of minutes. - - To monitor the number of lease transfers, open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}), select the **Replication** dashboard, hover over the **Range Operations** graph, and check the **Lease Transfers** data point. - - To check the number of snapshots, open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}), select the **Replication** dashboard, and hover over the **Snapshots** graph. - - TPC-C 140k replication and partitioning dashboards - -## Step 6. Allocate partitions - -Before running the benchmark, it's important to allocate partitions to workload binaries properly to ensure that the cluster is balanced. - -1. Create an `addrs` file containing connection strings to all 81 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable ... - ~~~ - -1. Upload the `addrs` file to the 5 VMs with the `workload` binary: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp addrs @:. - ~~~ - -1. SSH to each VM with `workload` and allocate partitions: - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload1.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions 81 \ - --warehouses 140000 \ - --partition-affinity=17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload2.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload3.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload4.histogram.ndjson \ - $(cat addrs) - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - ulimit -n 500000 && cockroach workload run tpcc \ - --partitions=81 \ - --warehouses=140000 \ - --partition-affinity=65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80 \ - --ramp=30m \ - --duration=1ms \ - --histograms=workload5.histogram.ndjson \ - $(cat addrs) - ~~~ - -## Step 7. Run the benchmark - -Once the allocations finish, run TPC-C for 30 minutes on each VM with `workload`: - -{{site.data.alerts.callout_info}} -It is critical to run the benchmark from the workload nodes in parallel, so start them as simultaneously as possible. -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload1.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload2.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload3.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partitions=81 \ ---warehouses=140000 \ ---partition-affinity=49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload4.histogram.ndjson \ -$(cat addrs) -~~~ - -{% include_cached copy-clipboard.html %} -~~~ shell -ulimit -n 500000 && cockroach workload run tpcc \ ---partition=81 \ ---warehouses=140000 \ ---partition-affinity=65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80 \ ---ramp=4m \ ---duration=30m \ ---histograms=workload5.histogram.ndjson \ -$(cat addrs) -~~~ - -## Step 8. Interpret the results - -1. Collect the result files from each VM with `workload`: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload1.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload2.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload3.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload4.histogram.ndjson . - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp @:workload5.histogram.ndjson . - ~~~ - -1. Upload the result files to one of the VMs with the `workload` binary: - - {{site.data.alerts.callout_info}} - The following commands assume you're uploading to the VM with the `workload1.histogram.ndjson` file. - {{site.data.alerts.end}} - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload2.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload3.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload4.histogram.ndjson @:. - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ scp workload5.histogram.ndjson @:. - ~~~ - -1. SSH to the VM where you uploaded the results files. - -1. Run the `workload debug tpcc-merge-results` command to synthesize the results: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach workload debug tpcc-merge-results \ - --warehouses=140000 \ - workload*.histogram.ndjson - ~~~ - - You'll should see results similar to the following, with **1.68M tpmC with 140,000 warehouses, resulting in an efficiency score of 95%**: - - ~~~ - Duration: 30m1., Warehouses: 140000, Efficiency: 95.45, tpmC: 1684437.21 - _elapsed___ops/sec(cum)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1801.1s 2824.0 302.0 1140.9 2415.9 9126.8 55834.6 delivery - 1801.1s 28074.0 402.7 1409.3 2684.4 9126.8 45097.2 newOrder - 1801.1s 2826.0 6.8 62.9 125.8 4160.7 33286.0 orderStatus - 1801.1s 28237.4 251.7 1006.6 2415.9 15032.4 103079.2 payment - 1801.1s 2823.5 39.8 469.8 906.0 5905.6 38654.7 stockLevel - ~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.2/performance-benchmarking-with-tpcc-local-multiregion.md b/src/current/v26.2/performance-benchmarking-with-tpcc-local-multiregion.md deleted file mode 100644 index 8b8d05d6f7d..00000000000 --- a/src/current/v26.2/performance-benchmarking-with-tpcc-local-multiregion.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to run the TPC-C benchmark against CockroachDB -toc: true -toc_not_nested: true -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|--------------------------+-------------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -- Make sure you have already [installed CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}). - -## Step 1. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -In the terminal, use the [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) command to start a simulated multi-region cluster with 9 nodes: - -{% include_cached copy-clipboard.html %} -~~~ shell -cockroach demo --global --nodes 9 --no-example-database --insecure -~~~ - -This simulated multi-region deployment will take advantage of CockroachDB's [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) to deliver improved ease of use and performance. - -{{site.data.alerts.callout_info}} -You must use the IP address shown at the SQL prompt to run the following steps. - -This is necessary because the demo cluster may use a randomly allocated local IP that is not the `127.0.0.1` shown here. -{{site.data.alerts.end}} - -## Step 2. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -In a second terminal window (call it terminal 2), use [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}) to load the initial schema and data: - -{% include_cached copy-clipboard.html %} -~~~ shell -cockroach workload init tpcc \ ---warehouses=10 \ ---partitions=3 \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26257/tpcc?sslmode=disable' -~~~ - -This will load 2 GB of data for 10 "warehouses", and spread the data across all 3 regions with a [`ZONE` survival goal]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#survive-zone-failures). - -## Step 3. Run the benchmark - -Run the workload for 10 "warehouses" of data for ten minutes. In order to spread the simulated workload across the 3 regions specified in the previous step, you will need to start each of the following commands from 3 different terminals: - -In terminal 2: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=0 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26257/tpcc?sslmode=disable' -~~~ - -In terminal 3: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=1 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26260/tpcc?sslmode=disable' -~~~ - -In terminal 4: - -{% include_cached copy-clipboard.html %} -~~~ sql -cockroach workload run tpcc \ ---warehouses=10 \ ---duration=10m \ ---wait=true \ ---partitions=3 \ ---partition-affinity=2 \ ---tolerate-errors \ ---survival-goal zone \ ---regions=europe-west1,us-east1,us-west1 \ -'postgresql://root@127.0.0.1:26263/tpcc?sslmode=disable' -~~~ - -You'll see per-operation statistics every second: - -~~~ -Initializing 20 connections... -Initializing 100 workers and preparing statements... -_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 delivery - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 newOrder -... - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 delivery - 105.0s 0 4.0 1.8 44.0 46.1 46.1 46.1 newOrder - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 orderStatus - 105.0s 0 1.0 2.0 14.7 14.7 14.7 14.7 payment - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 stockLevel -... -~~~ - -{{site.data.alerts.callout_success}} -For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other built-in load generators, use `cockroach workload run --help`. -{{site.data.alerts.end}} - -## Step 4. Interpret the results - -Once the `workload` has finished running, you'll see a final output line in each terminal window. - -In terminal 2: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 33.2% 170.6 44.0 536.9 872.4 1543.5 3087.0 -~~~ - -In terminal 3: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 28.4% 147.0 41.9 453.0 671.1 1342.2 1946.2 -~~~ - -In terminal 4: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 600.0s 36.5 28.4% 222.8 46.1 704.6 1140.9 1744.8 2952.8 -~~~ - -You will also see some audit checks and latency statistics for each individual query in each terminal. Some of those checks might indicate that they were `SKIPPED` due to insufficient data since this is a small run on a small machine. For a more comprehensive test, run `workload` for a longer duration (e.g., two hours). The `tpmC` (new order transactions/minute) number is the headline number and `efc` ("efficiency") tells you how close CockroachDB gets to theoretical maximum `tpmC`. In a perfect execution, the sum of efficiency across all partitions would be 100%. - -## Step 5. Clean up - -When you're done with your test cluster, switch back to terminal 1 where [`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) is still running and issue `\q` at the SQL prompt to gracefully shut down the demo cluster. - -{% include_cached copy-clipboard.html %} -~~~ sql -\q -~~~ diff --git a/src/current/v26.2/performance-benchmarking-with-tpcc-local.md b/src/current/v26.2/performance-benchmarking-with-tpcc-local.md deleted file mode 100644 index 133bab2d3dd..00000000000 --- a/src/current/v26.2/performance-benchmarking-with-tpcc-local.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C 13k on 3 nodes on your laptop -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-10-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -- Make sure you have already [installed CockroachDB]({% link {{ page.version.version }}/install-cockroachdb.md %}). - -## Step 1. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. In separate terminal windows, use the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command to start 3 nodes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local1 \ - --listen-addr=localhost:26257 \ - --http-addr=localhost:8080 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local2 \ - --listen-addr=localhost:26258 \ - --http-addr=localhost:8081 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach start \ - --insecure \ - --store=tpcc-local3 \ - --listen-addr=localhost:26259 \ - --http-addr=localhost:8082 \ - --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - -1. Use the [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to perform a one-time initialization of the cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach init \ - --insecure \ - --host=localhost:26257 - ~~~ - -## Step 2. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -Use [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}) to load the initial schema and data: - -{% include_cached copy-clipboard.html %} -~~~ shell -$ cockroach workload fixtures import tpcc \ ---warehouses=10 \ -'postgresql://root@localhost:26257?sslmode=disable' -~~~ - -This will load 2 GB of data for 10 "warehouses". - -## Step 3. Run the benchmark - -Run the workload for ten "warehouses" of data for ten minutes: - -{% include_cached copy-clipboard.html %} -~~~ shell -$ cockroach workload run tpcc \ ---warehouses=10 \ ---ramp=3m \ ---duration=10m \ -'postgresql://root@localhost:26257?sslmode=disable' -~~~ - -You'll see per-operation statistics every second: - -~~~ -Initializing 20 connections... -Initializing 100 workers and preparing statements... -_elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms) - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 delivery - 1.0s 0 0.0 0.0 0.0 0.0 0.0 0.0 newOrder -... - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 delivery - 105.0s 0 4.0 1.8 44.0 46.1 46.1 46.1 newOrder - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 orderStatus - 105.0s 0 1.0 2.0 14.7 14.7 14.7 14.7 payment - 105.0s 0 0.0 0.2 0.0 0.0 0.0 0.0 stockLevel -... -~~~ - -{{site.data.alerts.callout_success}} -For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other built-in load generators, use `cockroach workload run --help`. -{{site.data.alerts.end}} - -## Step 4. Interpret the results - -Once the `workload` has finished running, you'll see a final output line: - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 300.0s 121.6 94.6% 41.0 39.8 54.5 71.3 96.5 130.0 -~~~ - -You will also see some audit checks and latency statistics for each individual query. For this run, some of those checks might indicate that they were `SKIPPED` due to insufficient data. For a more comprehensive test, run `workload` for a longer duration (e.g., two hours). The `tpmC` (new order transactions/minute) number is the headline number and `efc` ("efficiency") tells you how close CockroachDB gets to theoretical maximum `tpmC`. - -The [TPC-C specification](http://www.tpc.org/tpc_documents_current_versions/pdf/tpc-c_v5.11.0.pdf) has p90 latency requirements in the order of seconds, but as you see here, CockroachDB far surpasses that requirement with p90 latencies in the tens of milliseconds. - -## Step 5. Clean up - -1. When you're done with your test cluster, stop the nodes. - - Get the process IDs of the nodes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - ps -ef | grep cockroach | grep -v grep - ~~~ - - ~~~ - 501 4482 1 0 2:41PM ttys000 0:09.78 cockroach start --insecure --store=tpcc-local1 --listen-addr=localhost:26257 --http-addr=localhost:8080 --join=localhost:26257,localhost:26258,localhost:26259 - 501 4497 1 0 2:41PM ttys000 0:08.54 cockroach start --insecure --store=tpcc-local2 --listen-addr=localhost:26258 --http-addr=localhost:8081 --join=localhost:26257,localhost:26258,localhost:26259 - 501 4503 1 0 2:41PM ttys000 0:08.54 cockroach start --insecure --store=tpcc-local3 --listen-addr=localhost:26259 --http-addr=localhost:8082 --join=localhost:26257,localhost:26258,localhost:26259 - ~~~ - - Gracefully shut down each node, specifying its process ID: - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4482 - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4497 - ~~~ - - {{site.data.alerts.callout_info}} - For the last node, the shutdown process will take longer (about a minute) and will eventually stop the node. This is because, with only 1 of 3 nodes left, all ranges no longer have a majority of replicas available, and so the cluster is no longer operational. - {{site.data.alerts.end}} - - {% include_cached copy-clipboard.html %} - ~~~ shell - kill -TERM 4503 - ~~~ - -1. To restart the cluster at a later time, run the same `cockroach start` commands as earlier from the directory containing the nodes' data stores. - - If you do not plan to restart the cluster, you may want to remove the nodes' data stores: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ rm -rf tpcc-local1 tpcc-local2 tpcc-local3 - ~~~ diff --git a/src/current/v26.2/performance-benchmarking-with-tpcc-medium.md b/src/current/v26.2/performance-benchmarking-with-tpcc-medium.md deleted file mode 100644 index 17433899aba..00000000000 --- a/src/current/v26.2/performance-benchmarking-with-tpcc-medium.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Benchmark CockroachDB against TPC-C with 15 nodes on `c5d.4xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-10k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -- [Review TPC-C concepts](#review-tpc-c-concepts) -- [Request a trial license](#request-a-trial-license) - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -### Request a trial license - -Reproducing these TPC-C results involves using CockroachDB's [partitioning]({% link {{ page.version.version }}/partitioning.md %}) feature to ensure replicas for any given section of data are located on the same nodes that will be queried by the load generator for that section of data. Partitioning helps distribute the workload evenly across the cluster. - -The partitioning feature requires an Enterprise license, so [request a 30-day trial license](https://www.cockroachlabs.com/get-cockroachdb/enterprise/) before you get started. - -You should receive your trial license via email within a few minutes. You'll enable your license once your cluster is up-and-running. - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 16 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 15 for CockroachDB nodes and 1 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.4xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Run the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 \ - --locality=rack=0 - ~~~ - - Each node will start with a [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) that includes an artificial "rack number" (e.g., `--locality=rack=0`). Use 5 racks for 15 nodes so that 3 nodes will be assigned to each rack. - -1. Repeat steps 1 - 3 for the other 14 VMs for CockroachDB nodes. Each time, be sure to: - - Adjust the `--advertise-addr` flag. - - Set the [`--locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality) flag to the appropriate "rack number". - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Configure the cluster - -You'll be importing a large TPC-C data set. To speed that up, you can tweak some cluster settings. You'll also need to enable the Enterprise license you requested earlier. - -1. SSH to any VM with the `cockroach` binary. - -1. Launch the [built-in SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach sql --insecure --host=
    - ~~~ - -1. Adjust some [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING rocksdb.ingest_backpressure.l0_file_count_threshold = 100; - SET CLUSTER SETTING schemachanger.backfiller.max_buffer_size = '5 GiB'; - SET CLUSTER SETTING kv.snapshot_rebalance.max_rate = '128 MiB'; - SET CLUSTER SETTING rocksdb.min_wal_sync_interval = '500us'; - SET CLUSTER SETTING kv.range_merge.queue_enabled = false; - ~~~ - -1. Enable the trial license you requested earlier: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING cluster.organization = ''; - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SET CLUSTER SETTING enterprise.license = ''; - ~~~ - -1. Exit the SQL shell: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > \q - ~~~ - -## Step 4. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --partitions=5 \ - --warehouses=13000 \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 1.04 TB of data for 13,000 "warehouses". This can take around 1 hour to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 5. Allow the cluster to rebalance - -Next, [partition your database]({% link {{ page.version.version }}/partitioning.md %}) to divide all of the TPC-C tables and indexes into 5 partitions, one per rack, and then use [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) to pin those partitions to a particular rack. - -1. Still on the same VM, briefly run TPC-C to let the cluster balance and the leases settle. Bump the file descriptor limits with `ulimit` to the high value shown in the following snippet, since the workload generators create a lot of database connections. - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ ulimit -n 100000 && cockroach workload run tpcc \ - --partitions=5 \ - --warehouses=13000 \ - --duration=1m \ - --ramp=1ms \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - -1. Wait for range rebalancing to finish. - - This will likely take 10s of minutes. To watch the progress, go to the **Metrics > Queues > Replication Queue** graph in the DB Console. Once the **Replication Queue** gets to `0` for all actions and stays there, you can move on to the next step. - -## Step 6. Run the benchmark - -1. Back on the VM with the `workload` binary, create an `addrs` file containing connection strings to all 15 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable ... - ~~~ - -1. Run TPC-C for 30 minutes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ ulimit -n 100000 && cockroach workload run tpcc \ - --partitions=5 \ - --warehouses=13000 \ - --ramp=1m \ - --duration=30m \ - $(cat addrs) - ~~~ - -## Step 7. Interpret the results - -Once the workload has finished running, you will see a result similar to the following. The efficiency and latency can be combined to determine whether this was a passing run. You should expect to see an efficiency number above 95%, well above the required minimum of 85%, and p95 latencies well below the required maximum of 10 seconds. - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1800.0s 160420.0 96.0% 303.1 285.2 570.4 671.1 939.5 4160.7 -~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.2/performance-benchmarking-with-tpcc-small.md b/src/current/v26.2/performance-benchmarking-with-tpcc-small.md deleted file mode 100644 index a6c32eef6a4..00000000000 --- a/src/current/v26.2/performance-benchmarking-with-tpcc-small.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Performance Benchmarking with TPC-C -summary: Learn how to benchmark CockroachDB against TPC-C with 3 nodes on `c5d.4xlarge` machines -toc: true -toc_not_nested: true -key: performance-benchmarking-with-tpc-c-1k-warehouses.html -docs_area: reference.benchmarking ---- - -This page shows you how to reproduce [CockroachDB TPC-C performance benchmarking results]({% link {{ page.version.version }}/performance.md %}#scale). Across all scales, CockroachDB can process tpmC (new order transactions per minute) at near maximum efficiency. Start by choosing the scale you're interested in: - -{% include {{ page.version.version }}/filter-tabs/perf-bench-tpc-c.md %} - -| Workload | Cluster size | Warehouses | Data size | -|----------------------+---------------------------------------------------------+------------+-----------| -| Local | 3 nodes on your laptop | 10 | 2 GB | -| Local (multi-region) | 9 in-memory nodes on your laptop using `cockroach demo` | 10 | 2 GB | -| Small | 3 nodes on `c5d.4xlarge` machines | 2500 | 200 GB | -| Medium | 15 nodes on `c5d.4xlarge` machines | 13,000 | 1.04 TB | -| Large | 81 nodes on `c5d.9xlarge` machines | 140,000 | 11.2 TB | - -## Before you begin - -### Review TPC-C concepts - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. Before you get started, consider reviewing [what TPC-C is and how it is measured]({% link {{ page.version.version }}/performance.md %}#tpc-c). - -## Step 1. Set up the environment - -- [Provision VMs](#provision-vms) -- [Configure your network](#configure-your-network) - -### Provision VMs - -1. [Create 4 VM instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html), 3 for CockroachDB nodes and 1 for the TPC-C workload. - - Create all instances in the same region and the same security group. - - Use the `c5d.4xlarge` machine type. - - Use [local SSD instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#instance-store-volumes). Local SSDs are low latency disks attached to each VM, which maximizes performance. This configuration best resembles what a bare metal deployment would look like, with machines directly connected to one physical disk each. We do not recommend using network-attached block storage. - -1. Note the internal IP address of each instance. You'll need these addresses when starting the CockroachDB nodes. - -{{site.data.alerts.callout_danger}} -This configuration is intended for performance benchmarking only. For production deployments, there are other important considerations, such as security, load balancing, and data location techniques to minimize network latency. For more details, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}). -{{site.data.alerts.end}} - -### Configure your network - -CockroachDB requires TCP communication on two ports: - -- `26257` for inter-node communication (i.e., working as a cluster) and for the TPC-C workload to connect to nodes -- `8080` for exposing your DB Console - -[Create inbound rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) for your security group: - -#### Inter-node and TPCC-to-node communication - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **26257** - Source | The name of your security group (e.g., *sg-07ab277a*) - -#### DB Console - - Field | Recommended Value --------|------------------- - Type | Custom TCP Rule - Protocol | TCP - Port Range | **8080** - Source | Your network's IP ranges - -## Step 2. Start CockroachDB - -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} - -1. SSH to the first VM where you want to run a CockroachDB node. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Run the [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) command: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach start \ - --insecure \ - --advertise-addr= \ - --join=,, \ - --cache=.25 - ~~~ - -1. Repeat steps 1 - 3 for the other 2 VMs for CockroachDB nodes. Each time, be sure to adjust the `--advertise-addr` flag. - -1. On any of the VMs with the `cockroach` binary, run the one-time [`cockroach init`]({% link {{ page.version.version }}/cockroach-init.md %}) command to join the first nodes into a cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach init --insecure --host=
    - ~~~ - -## Step 3. Import the TPC-C dataset - -CockroachDB comes with a number of [built-in workloads]({% link {{ page.version.version }}/cockroach-workload.md %}) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload. - -1. SSH to the VM where you want to run TPC-C. - -1. [Install CockroachDB for Linux]({% link {{ page.version.version }}/install-cockroachdb-linux.md %}). - -1. Import the TPC-C dataset: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload fixtures import tpcc \ - --warehouses=2500 \ - 'postgres://root@
    :26257?sslmode=disable' - ~~~ - - This will load 200 GB of data for 2500 "warehouses". This can take a while to complete. - - You can monitor progress on the **Jobs** screen of the DB Console. Open the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) by pointing a browser to the address in the `admin` field in the standard output of any node on startup. - -## Step 4. Run the benchmark - -1. Still on the same VM, create an `addrs` file containing connection strings to the 3 CockroachDB nodes: - - ~~~ - postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable postgres://root@:26257?sslmode=disable - ~~~ - -1. Run TPC-C for 30 minutes: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cockroach workload run tpcc \ - --warehouses=2500 \ - --ramp=1m \ - --duration=30m \ - $(cat addrs) - ~~~ - -## Step 5. Interpret the results - -Once the workload has finished running, you will see a result similar to the following. The efficiency and latency can be combined to determine whether this was a passing run. You should expect to see an efficiency number above 95%, well above the required minimum of 85%, and p95 latencies well below the required maximum of 10 seconds. - -~~~ -_elapsed_______tpmC____efc__avg(ms)__p50(ms)__p90(ms)__p95(ms)__p99(ms)_pMax(ms) - 1800.0s 31064.6 96.6% 107.4 88.1 243.3 302.0 402.7 973.1 -~~~ - -## See also - -- [Performance Overview]({% link {{ page.version.version }}/performance.md %}) - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v26.2/performance.md b/src/current/v26.2/performance.md deleted file mode 100644 index a79e600d8d8..00000000000 --- a/src/current/v26.2/performance.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Benchmarking Overview -summary: An overview of the performance profiles you can expect from CockroachDB. -toc: true -toc_not_nested: true -docs_area: reference.benchmarking ---- - -CockroachDB delivers predictable throughput and latency at all scales on commodity hardware. This page provides an overview of the performance profiles you can expect, based on Cockroach Labs's extensive testing using the TPC-C industry-standard benchmark. - -For instructions to reproduce the TPC-C results listed here, see [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-large.md %}). If you fail to achieve similar results, there is likely a problem in either the hardware, workload, or test design. - -{{site.data.alerts.callout_success}} -This document is about CockroachDB performance on benchmarks. For guidance on tuning real workloads, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on data location techniques to minimize network latency, see [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}). -{{site.data.alerts.end}} - -## Scale - -TPC-C provides the most realistic and objective measure for OLTP performance at various scale factors. During testing, CockroachDB v21.1 processed **1.68M tpmC with 140,000 warehouses, resulting in an efficiency score of 95%.** As shown in the following chart, this was a 40% improvement over the results from CockroachDB 19.2. - -For a refresher on what exactly TPC-C is and how it is measured, see [Benchmark details](#benchmark-details). - -CockroachDB achieves this performance in [`SERIALIZABLE` isolation]({% link {{ page.version.version }}/demo-serializable.md %}), the strongest isolation level in the SQL standard. - -TPC-C 140,000 - -| Metric | CockroachDB 19.2 | CockroachDB 21.1 | -|-------------------------------------------------+------------------+------------------| -| Max warehouses with max efficiency (warehouses) | 100,000 | 140,000 | -| Max throughput (tpmC) | 1,245,462 | 1,684,437 | -| Efficiency (%) | 98.81 | 95.45 | -| Max number of rows (billion) | 49.8 | 69.7 | -| Max unreplicated data (TB) | 8 | 11.2 | -| Number of nodes | 81 | 81 | - -### Linear scaling - -CockroachDB has **no theoretical scaling limit** and, in practice, can achieve near-linear performance at 256 nodes. Because the TPC-C results reflect leaps in scale, to test linear scaling, Cockroach Labs ran a simple benchmark named KV 95 (95% point reads, 5% point writes, all uniformly distributed) on AWS `c5d.4xlarge` machines: - -CRDB Linear Scale - -This chart shows that adding nodes increases throughput linearly while holding p50 and p99 latency constant. The concurrency for each scale was chosen to optimize throughput while maintaining an acceptable latency and can be observed in the following table. - -| Number of nodes | Workers | Concurrency | -|-----------------+---------+-------------| -| 16 | 2 | 512 | -| 32 | 4 | 512 | -| 64 | 4 | 1024 | -| 128 | 8 | 1024 | -| 256 | 8 | 2048 | - -## Throughput - -Cockroach Labs believes TPC-C provides the most realistic and objective measure for OLTP throughput. In the real world, applications generate transactional workloads that consist of a combination of reads and writes, possibly with concurrency and likely without all data being loaded into memory. Approach benchmark results quoted in QPS with caution, because anything as simple as a “query” is unlikely to be representative of the workload you need to run in practice. - -## Latency - -CockroachDB returns single-row **reads in 1 ms** and processes single-row **writes in 2 ms** within a single availability zone. As you expand out to multiple availability zones or multiple regions, latency can increase due to distance and the limitation of the speed of light. - -For benchmarking latency, again, Cockroach Labs believes TPC-C provides the most realistic and objective measure, since it encompasses the latency distribution, including tail performance. - -CockroachDB provides a number of important tuning practices for both single-region and multi-region deployments, including [secondary indexes]({% link {{ page.version.version }}/indexes.md %}) and various [data topologies]({% link {{ page.version.version }}/topology-patterns.md %}) to achieve low latency. - -## Benchmark details - -### TPC-C - -Cockroach Labs measures performance through many diverse tests, including the [industry-standard OLTP benchmark TPC-C](http://www.tpc.org/tpcc/), which simulates an e-commerce or retail company. Created in 1992, TPC-C has withstood the test of time and remains the most mature industry benchmark for OLTP workloads, and **the only objective comparison for evaluating OLTP performance**. In its own words, TPC-C: - ->“…involves a mix of five concurrent transactions of different types and complexity either executed on-line or queued for deferred execution. The database is comprised of nine types of tables with a wide range of record and population sizes. While the benchmark portrays the activity of a wholesale supplier, TPC-C is not limited to the activity of any particular business segment, but, rather represents any industry that must manage, sell, or distribute a product or service.” - -As a result, TPC-C includes create, read, update, and delete (e.g., CRUD) queries, basic joins, and other SQL statements used to administer mission-critical transactional workloads. It includes detailed specifications for concurrency and workload [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention). - -#### How TPC-C works - -TPC-C measures the throughput and latency for processing sales through a customer warehouse using a “business throughput” metric called **tpmC** that measures the number of order transactions performed per minute throughout the system. This metric is considerably more realistic than TPS (transactions per second) or QPS (queries per second) alone because it summarizes multiple transactions per order and accounts for failed transactions. TPC-C also has several latency requirements that apply to median, p90, and max latencies. - -TPC-C specifies restrictions on the maximum throughput achievable per warehouse. This is done to ensure that as a system becomes progressively more capable of throughput, it must also deal with progressively more data. This is how things work in the real world, and it makes little sense to say that your database can process a bazillion transactions per second if it’s processing the same data over and over again. - -Because TPC-C is constrained to a maximum amount of throughput per warehouse, we often discuss TPC-C performance as the **maximum number of warehouses for which a database can maintain the maximum throughput per minute.** For a full description of the benchmark, see [TPC BENCHMARK™ C Standard Specification Revision 5.11](http://www.tpc.org/tpc_documents_current_versions/pdf/tpc-c_v5.11.0.pdf). - -## Performance limitations - -CockroachDB has no theoretical limitations to scaling, throughput, latency, or concurrency other than the speed of light. - -## See also - -- Hardware - - CockroachDB works well on commodity hardware in public cloud, private cloud, on-prem, and hybrid environments. For hardware recommendations, see our [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). - -- Performance tuning - - For guidance on tuning a real workload's performance, see [SQL Best Practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), and for guidance on techniques to minimize network latency in multi-region or global clusters, see [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}). - -- TPC-C replication instructions - - For instructions showing how to replicate the TPC-C results described in this page, see [Performance Benchmarking with TPC-C]({% link {{ page.version.version }}/performance-benchmarking-with-tpcc-large.md %}). diff --git a/src/current/v26.2/query-behavior-troubleshooting.md b/src/current/v26.2/query-behavior-troubleshooting.md index ade3c491e57..938ca0f382e 100644 --- a/src/current/v26.2/query-behavior-troubleshooting.md +++ b/src/current/v26.2/query-behavior-troubleshooting.md @@ -366,7 +366,7 @@ A response of `bad connection` or `closed` normally indicates that the node to w Once you find the node, you can check its [logs]({% link {{ page.version.version }}/logging.md %}) (stored in `cockroach-data/logs` by [default]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration)). -Because this kind of behavior is unexpected, you should [file an issue]({% link {{ page.version.version }}/file-an-issue.md %}). +Because this kind of behavior is unexpected, you should file an issue on Github. ### Log queries executed by a specific node diff --git a/src/current/v26.2/regional-tables.md b/src/current/v26.2/regional-tables.md index bd9a1bd3184..868e7e49e87 100644 --- a/src/current/v26.2/regional-tables.md +++ b/src/current/v26.2/regional-tables.md @@ -110,7 +110,7 @@ By default, all tables in a multi-region database are [regional tables](#regiona {% include {{page.version.version}}/sql/locality-optimized-search.md %} {{site.data.alerts.callout_success}} -A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. For a tutorial showing how table localities can improve performance metrics across a multi-region cluster, see [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). +A good way to check that your [table locality settings]({% link {{ page.version.version }}/multiregion-overview.md %}#table-locality) are having the expected effect is by monitoring how the performance metrics of a workload change as the settings are applied to a running cluster. {{site.data.alerts.end}} ## Characteristics @@ -132,10 +132,6 @@ For more information about how to choose a database survival goal, see [When to - If rows in the table **cannot** be tied to specific geographies, reads must be up-to-date for business reasons or because the table is referenced by [foreign keys]({% link {{ page.version.version }}/foreign-key.md %}), and the table is rarely modified, consider the [`GLOBAL` Table Locality Pattern]({% link {{ page.version.version }}/global-tables.md %}). - If your application can tolerate historical reads in some cases, consider the [Follower Reads pattern]({% link {{ page.version.version }}/topology-follower-reads.md %}). -## Tutorial - -For a step-by-step demonstration showing how CockroachDB's multi-region capabilities (including [`REGIONAL BY ROW` tables](#regional-by-row-tables)) give you low-latency reads in a distributed cluster, see the tutorial on [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}). - ## Demo video If you'd prefer to watch a video on Regional Tables, check out the following video: diff --git a/src/current/v26.2/secure-a-cluster.md b/src/current/v26.2/secure-a-cluster.md index 941b778f5b8..636fd2aa6d4 100644 --- a/src/current/v26.2/secure-a-cluster.md +++ b/src/current/v26.2/secure-a-cluster.md @@ -460,7 +460,7 @@ Adding capacity is as simple as starting more nodes with `cockroach start`. - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and JSON support({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and JSON support({% link {{ page.version.version }}/jsonb.md %}) You might also be interested in the following pages: diff --git a/src/current/v26.2/show-locality.md b/src/current/v26.2/show-locality.md index 82b2152eb80..983e50d381e 100644 --- a/src/current/v26.2/show-locality.md +++ b/src/current/v26.2/show-locality.md @@ -79,7 +79,6 @@ For a more extensive example, see [Create a table with node locality information ## See also -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) - [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %}) - [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) diff --git a/src/current/v26.2/show-partitions.md b/src/current/v26.2/show-partitions.md index c7f2e8a1bbd..528853f58ad 100644 --- a/src/current/v26.2/show-partitions.md +++ b/src/current/v26.2/show-partitions.md @@ -237,4 +237,3 @@ If a partitioned table has no zones configured, the `SHOW CREATE TABLE` output i - [Define Table Partitions]({% link {{ page.version.version }}/partitioning.md %}) - [SQL Statements]({% link {{ page.version.version }}/sql-statements.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) diff --git a/src/current/v26.2/simulate-a-multi-region-cluster-on-localhost.md b/src/current/v26.2/simulate-a-multi-region-cluster-on-localhost.md index f77db92ae17..6c84c2a96da 100644 --- a/src/current/v26.2/simulate-a-multi-region-cluster-on-localhost.md +++ b/src/current/v26.2/simulate-a-multi-region-cluster-on-localhost.md @@ -95,6 +95,5 @@ When you're done with your demo cluster, you can wipe the cluster by typing the - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - Further explore CockroachDB capabilities like: - - [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}) - [Serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}) diff --git a/src/current/v26.2/start-a-local-cluster-in-docker-linux.md b/src/current/v26.2/start-a-local-cluster-in-docker-linux.md index fe34cbaa255..4aca92a6ac4 100644 --- a/src/current/v26.2/start-a-local-cluster-in-docker-linux.md +++ b/src/current/v26.2/start-a-local-cluster-in-docker-linux.md @@ -37,4 +37,4 @@ Once you've [installed the official CockroachDB Docker image]({% link {{ page.ve - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.2/start-a-local-cluster-in-docker-mac.md b/src/current/v26.2/start-a-local-cluster-in-docker-mac.md index 8dabc54bc70..b929ec0b47f 100644 --- a/src/current/v26.2/start-a-local-cluster-in-docker-mac.md +++ b/src/current/v26.2/start-a-local-cluster-in-docker-mac.md @@ -34,4 +34,4 @@ Once you've [installed the official CockroachDB Docker image]({% link {{ page.ve - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.2/start-a-local-cluster-in-docker-windows.md b/src/current/v26.2/start-a-local-cluster-in-docker-windows.md index a3568fd183c..2f87631b419 100644 --- a/src/current/v26.2/start-a-local-cluster-in-docker-windows.md +++ b/src/current/v26.2/start-a-local-cluster-in-docker-windows.md @@ -366,4 +366,4 @@ The CockroachDB [DB Console]({% link {{ page.version.version }}/ui-overview.md % - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.2/start-a-local-cluster.md b/src/current/v26.2/start-a-local-cluster.md index f2f6af525ef..e0b286846d9 100644 --- a/src/current/v26.2/start-a-local-cluster.md +++ b/src/current/v26.2/start-a-local-cluster.md @@ -389,4 +389,4 @@ Adding capacity is as simple as starting more nodes with `cockroach start`. - [Create a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?experience=enterprise) where you can [generate and manage licenses]({% link {{ page.version.version }}/licensing-faqs.md %}) for CockroachDB installations - [Install the client driver]({% link {{ page.version.version }}/install-client-drivers.md %}) for your preferred language - Learn more about [CockroachDB SQL]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}) and the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) -- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) +- Further explore CockroachDB capabilities like [fault tolerance and automated repair]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), [multi-region performance]({% link {{ page.version.version }}/multiregion-overview.md %}), [serializable transactions]({% link {{ page.version.version }}/demo-serializable.md %}), and [JSON support]({% link {{ page.version.version }}/jsonb.md %}) diff --git a/src/current/v26.2/support-resources.md b/src/current/v26.2/support-resources.md index d4ac13b822f..0474ef39a6c 100644 --- a/src/current/v26.2/support-resources.md +++ b/src/current/v26.2/support-resources.md @@ -13,6 +13,5 @@ If you're having an issue with CockroachDB, you can reach out for support from C - [CockroachDB Community Forum](https://forum.cockroachlabs.com) - [CockroachDB Community Slack](https://cockroachdb.slack.com) - [CockroachDB in StackOverflow](http://stackoverflow.com/questions/tagged/cockroachdb) -- [File an issue in GitHub]({% link {{ page.version.version }}/file-an-issue.md %}) We also rely on contributions from users like you. If you know how to help users who might be struggling with a problem, we hope you will! diff --git a/src/current/v26.2/table-localities.md b/src/current/v26.2/table-localities.md index ac711dc5030..9e84ecff1e9 100644 --- a/src/current/v26.2/table-localities.md +++ b/src/current/v26.2/table-localities.md @@ -66,10 +66,8 @@ Use a [`GLOBAL` table locality]({% link {{ page.version.version }}/table-localit - [Multi-Region Capabilities Overview]({% link {{ page.version.version }}/multiregion-overview.md %}) - [How to Choose a Multi-Region Configuration]({% link {{ page.version.version }}/choosing-a-multi-region-configuration.md %}) - [When to Use `ZONE` vs. `REGION` Survival Goals]({% link {{ page.version.version }}/multiregion-survival-goals.md %}#when-to-use-zone-vs-region-survival-goals) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}) - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) - [Disaster Recovery]({% link {{ page.version.version }}/disaster-recovery-planning.md %}) -- [Migrate to Multi-Region SQL]({% link {{ page.version.version }}/migrate-to-multiregion-sql.md %}) - [Secondary regions]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) - [`SET SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#set-secondary-region) - [`DROP SECONDARY REGION`]({% link {{ page.version.version }}/alter-database.md %}#drop-secondary-region) diff --git a/src/current/v26.2/troubleshooting-overview.md b/src/current/v26.2/troubleshooting-overview.md index e4b911aadbd..ed015771ef2 100644 --- a/src/current/v26.2/troubleshooting-overview.md +++ b/src/current/v26.2/troubleshooting-overview.md @@ -26,7 +26,6 @@ If you experience an issue when using CockroachDB, try these steps to resolve th - If you cannot resolve the issue yourself, the following tools can help you move forward: - [Support Resources]({% link {{ page.version.version }}/support-resources.md %}) identify ways you can get help with troubleshooting. - - [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %}) provides details on how to file an issue that you're unable to resolve. - In a support escalation, you may be directed to use the following features by the [Cockroach Labs support team]({% link {{ page.version.version }}/support-resources.md %}): diff --git a/src/current/v26.2/ui-network-latency-page.md b/src/current/v26.2/ui-network-latency-page.md index 7cce85e0c9e..94f01ebea65 100644 --- a/src/current/v26.2/ui-network-latency-page.md +++ b/src/current/v26.2/ui-network-latency-page.md @@ -30,7 +30,7 @@ Rows represent origin nodes, and columns represent destination nodes. Hover over The page automatically refreshes every 30 seconds to show the most recent information. -On a [typical multi-region cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %}), you can expect much lower latencies between nodes in the same region/availability zone. Nodes in different regions/availability zones, meanwhile, will experience higher latencies that reflect their geographical distribution. +On a [typical multi-region cluster]({% link {{ page.version.version }}/multiregion-overview.md %}), you can expect much lower latencies between nodes in the same region/availability zone. Nodes in different regions/availability zones, meanwhile, will experience higher latencies that reflect their geographical distribution. For instance, the cluster shown above has nodes in `us-west1`, `us-east1`, and `europe-west2`. Latencies are highest between nodes in `us-west1` and `europe-west2`, which span the greatest distance. This is especially clear when sorting by region or availability zone and collapsing nodes: @@ -81,6 +81,4 @@ Network latency limits the performance of individual operations. You can use the ## See also - [Topology Patterns]({% link {{ page.version.version }}/topology-patterns.md %}) -- [CockroachDB Performance]({% link {{ page.version.version }}/performance.md %}#latency) - [Performance Tuning]({% link {{ page.version.version }}/performance-best-practices-overview.md %}) -- [Low Latency Reads and Writes in a Multi-Region Cluster]({% link {{ page.version.version }}/demo-low-latency-multi-region-deployment.md %})