Revisions for pete and raphael

cockroachdb · jseldess · Sep 13, 2017 · Sep 12, 2017 · Sep 12, 2017 · Sep 12, 2017
commit e5fc562989b7ca75b8ccbcd474c4c106e5e41d6e
diff --git a/v1.0/manual-deployment-insecure.md b/v1.0/manual-deployment-insecure.md
@@ -57,7 +57,7 @@ This tutorial shows you how to manually deploy an insecure multi-node CockroachD
 	--host=<node1 internal address>
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it, in this case an internal address since you likely don't want applications outside your network reaching an insecure cluster. Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
+	This commands starts an insecure node and identifies the address at which other nodes can reach it, in this case an internal address since you likely don't want applications outside your network reaching an insecure cluster. Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 
 ## Step 2. Add nodes to the cluster
 

diff --git a/v1.1/deploy-cockroachdb-on-aws-insecure.md b/v1.1/deploy-cockroachdb-on-aws-insecure.md
@@ -128,7 +128,7 @@ AWS offers fully-managed load balancing to distribute traffic between instances.
     --background
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+	This commands starts an insecure node and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
 	Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-aws.md b/v1.1/deploy-cockroachdb-on-aws.md
@@ -269,7 +269,7 @@ Locally, you'll need to [create the following certificates and keys](create-secu
     --background
     ~~~
 
-    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
     Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, binds internal and client communication to port 26257, and binds Admin UI HTTP requests to port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-digital-ocean-insecure.md b/v1.1/deploy-cockroachdb-on-digital-ocean-insecure.md
@@ -108,7 +108,7 @@ For guidance, you can use Digital Ocean's guide to configuring firewalls based o
 	--background
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+	This commands starts an insecure node and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
 	Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-digital-ocean.md b/v1.1/deploy-cockroachdb-on-digital-ocean.md
@@ -246,7 +246,7 @@ Locally, you'll need to [create the following certificates and keys](create-secu
     --background
     ~~~
 
-    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
     Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, binds internal and client communication to port 26257, and binds Admin UI HTTP requests to port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-google-cloud-platform-insecure.md b/v1.1/deploy-cockroachdb-on-google-cloud-platform-insecure.md
@@ -127,7 +127,7 @@ To use GCE's TCP Proxy Load Balancing service:
 	--background
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+	This commands starts an insecure node and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
 	Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-google-cloud-platform.md b/v1.1/deploy-cockroachdb-on-google-cloud-platform.md
@@ -266,7 +266,7 @@ Locally, you'll need to [create the following certificates and keys](create-secu
     --background
     ~~~
 
-    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
     Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, binds internal and client communication to port 26257, and binds Admin UI HTTP requests to port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-microsoft-azure-insecure.md b/v1.1/deploy-cockroachdb-on-microsoft-azure-insecure.md
@@ -134,7 +134,7 @@ Microsoft Azure offers fully-managed load balancing to distribute traffic betwee
 	--background
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+	This commands starts an insecure node and identifies the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
 	Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/deploy-cockroachdb-on-microsoft-azure.md b/v1.1/deploy-cockroachdb-on-microsoft-azure.md
@@ -268,7 +268,7 @@ Locally, you'll need to [create the following certificates and keys](create-secu
     --background
     ~~~
 
-    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
     Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, binds internal and client communication to port 26257, and binds Admin UI HTTP requests to port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/manual-deployment-insecure.md b/v1.1/manual-deployment-insecure.md
@@ -60,7 +60,7 @@ This tutorial shows you how to manually deploy an insecure multi-node CockroachD
 	--background
 	~~~
 
-	This command sets the node to insecure and identifies the address at which other nodes can reach it, in this case an internal address since you likely don't want applications outside your network reaching an insecure cluster. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+	This commands starts an insecure node and identifies the address at which other nodes can reach it, in this case an internal address since you likely don't want applications outside your network reaching an insecure cluster. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
 	Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, listens for internal and client communication on port 26257, and listens for HTTP requests from the Admin UI on port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/manual-deployment.md b/v1.1/manual-deployment.md
@@ -194,7 +194,7 @@ Locally, you'll need to [create the following certificates and keys](create-secu
     --background
     ~~~
 
-    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory in order to improve read performance and prevent out-of-memory errors.
+    This command specifies the location of certificates and the address at which other nodes can reach it. It also increases the node's cache and temporary SQL memory size to 25% of available system memory to improve read performance and increase capacity for in-memory SQL processing (see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1) for more details).
 
     Otherwise, it uses all available defaults. For example, the node stores data in the `cockroach-data` directory, binds internal and client communication to port 26257, and binds Admin UI HTTP requests to port 8080. To set these options manually, see [Start a Node](start-a-node.html).
 

diff --git a/v1.1/operational-faqs.md b/v1.1/operational-faqs.md
@@ -31,7 +31,7 @@ flag.
 
 ## Why is memory usage increasing despite lack of traffic?
 
-Like most databases, CockroachDB caches the most recently accessed data in memory so that it can provide faster reads, and [its periodic writes of timeseries data](#why-is-disk-usage-increasing-despite-lack-of-writes) cause that cache size to increase until it hits its configured limit. For information about manually controlling the cache size, see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1)
+Like most databases, CockroachDB caches the most recently accessed data in memory so that it can provide faster reads, and [its periodic writes of timeseries data](#why-is-disk-usage-increasing-despite-lack-of-writes) cause that cache size to increase until it hits its configured limit. For information about manually controlling the cache size, see [Recommended Production Settings](recommended-production-settings.html#cache-and-sql-memory-size-changed-in-v1-1).
 
 ## Why is disk usage increasing despite lack of writes?
 

diff --git a/v1.1/recommended-production-settings.md b/v1.1/recommended-production-settings.md
@@ -46,9 +46,12 @@ For details about controlling the number and location of replicas, see [Configur
 
 ## Cache and SQL Memory Size <span class="version-tag">Changed in v1.1</span>
 
-By default, each node's cache and temporary SQL memory size is `128MiB` respectively. This default is optimal for running a local development cluster with multiple nodes on a single host. When running a production cluster with one node per host, however, these defaults may lead to out-of-memory errors. To prevent such errors and improve read performance, it's recommended to manually increase the cache and SQL memory size to 25% or more of available system memory.
+By default, each node's cache size and temporary SQL memory size is `128MiB` respectively. These defaults were chosen to facilitate development and testing, where users are likely to run multiple CockroachDB nodes on a single computer. When running a production cluster with one node per host, however, it's recommended to increase these values:
 
-To manually increase a node's cache size and SQL memory, start the node using the [`--cache`](start-a-node.html#flags) and [`--max-sql-memory`](start-a-node.html#flags) flags:
+- Increasing a node's **cache size** will improve the node's read performance.
+- Increasing a node's **SQL memory size** will increase the number of simultaneous client connections it allows (the `128MiB` default allows a maximum of 6200 simultaneous connections) as well as the node's capacity for in-memory processing of rows when using `ORDER BY`, `GROUP BY`, `DISTINCT`, joins, and window functions.
+
+To manually increase a node's cache size and SQL memory size, start the node using the [`--cache`](start-a-node.html#flags) and [`--max-sql-memory`](start-a-node.html#flags) flags:
 
 ~~~ shell
 $ cockroach start --cache=25% --max-sql-memory=25% <other start flags>