Managing sessions and queries

_includes/sidebar-data-v1.1.json

@@ -210,6 +210,12 @@
               "/${VERSION}/begin-transaction.html"
             ]
           },
+          {
+            "title": "<code>CANCEL QUERY</code>",
+            "urls": [
+              "/${VERSION}/cancel-query.html"
+            ]
+          },
           {
             "title": "<code>COMMIT</code>",
             "urls": [
@@ -444,6 +450,18 @@
               "/${VERSION}/show-index.html"
             ]
           },
+          {
+            "title": "<code>SHOW QUERIES</code>",
+            "urls": [
+              "/${VERSION}/show-queries.html"
+            ]
+          },
+          {
+            "title": "<code>SHOW SESSIONS</code>",
+            "urls": [
+              "/${VERSION}/show-sessions.html"
+            ]
+          },
           {
             "title": "<code>SHOW TABLES</code>",
             "urls": [
@@ -852,15 +870,9 @@
         ]
       },
       {
-        "title": "View Node Details",
-        "urls": [
-          "/${VERSION}/view-node-details.html"
-        ]
-      },
-      {
-        "title": "View Version Details",
+        "title": "Manage Long-Running Queries",
         "urls": [
-          "/${VERSION}/view-version-details.html"
+          "/${VERSION}/manage-long-running-queries.html"
         ]
       },
       {
@@ -899,6 +911,18 @@
           "/${VERSION}/generate-cockroachdb-resources.html"
         ]
       },
+      {
+        "title": "View Node Details",
+        "urls": [
+          "/${VERSION}/view-node-details.html"
+        ]
+      },
+      {
+        "title": "View Version Details",
+        "urls": [
+          "/${VERSION}/view-version-details.html"
+        ]
+      },
       {
         "title": "Diagnostics Reporting",
         "urls": [

_includes/sql/v1.1/diagrams/cancel_query.html

@@ -0,0 +1,19 @@
+<div><svg width="312" height="36">
+
+         <polygon points="9 17 1 13 1 21"></polygon>
+         <polygon points="17 17 9 13 9 21"></polygon>
+         <rect x="31" y="3" width="72" height="32" rx="10"></rect>
+         <rect x="29" y="1" width="72" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="39" y="21">CANCEL</text>
+         <rect x="123" y="3" width="68" height="32" rx="10"></rect>
+         <rect x="121" y="1" width="68" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="131" y="21">QUERY</text>
+
+            <rect x="211" y="3" width="74" height="32"></rect>
+            <rect x="209" y="1" width="74" height="32" class="nonterminal"></rect>
+            <text class="nonterminal" x="219" y="21">query_id</text>
+
+         <path class="line" d="m17 17 h2 m0 0 h10 m72 0 h10 m0 0 h10 m68 0 h10 m0 0 h10 m74 0 h10 m3 0 h-3"></path>
+         <polygon points="303 17 311 13 311 21"></polygon>
+         <polygon points="303 17 295 13 295 21"></polygon>
+      </svg></div>

_includes/sql/v1.1/diagrams/show_jobs.html

@@ -0,0 +1,14 @@
+<div><svg width="198" height="36">
+
+         <polygon points="9 17 1 13 1 21"></polygon>
+         <polygon points="17 17 9 13 9 21"></polygon>
+         <rect x="31" y="3" width="64" height="32" rx="10"></rect>
+         <rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="39" y="21">SHOW</text>
+         <rect x="115" y="3" width="56" height="32" rx="10"></rect>
+         <rect x="113" y="1" width="56" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="123" y="21">JOBS</text>
+         <path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m0 0 h10 m56 0 h10 m3 0 h-3"></path>
+         <polygon points="189 17 197 13 197 21"></polygon>
+         <polygon points="189 17 181 13 181 21"></polygon>
+      </svg></div>

_includes/sql/v1.1/diagrams/show_queries.html

@@ -0,0 +1,20 @@
+<div><svg width="362" height="112">
+
+         <polygon points="9 17 1 13 1 21"></polygon>
+         <polygon points="17 17 9 13 9 21"></polygon>
+         <rect x="31" y="3" width="64" height="32" rx="10"></rect>
+         <rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="39" y="21">SHOW</text>
+         <rect x="135" y="35" width="80" height="32" rx="10"></rect>
+         <rect x="133" y="33" width="80" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="143" y="53">CLUSTER</text>
+         <rect x="135" y="79" width="64" height="32" rx="10"></rect>
+         <rect x="133" y="77" width="64" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="143" y="97">LOCAL</text>
+         <rect x="255" y="3" width="80" height="32" rx="10"></rect>
+         <rect x="253" y="1" width="80" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="263" y="21">QUERIES</text>
+         <path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m20 0 h10 m0 0 h90 m-120 0 h20 m100 0 h20 m-140 0 q10 0 10 10 m120 0 q0 -10 10 -10 m-130 10 v12 m120 0 v-12 m-120 12 q0 10 10 10 m100 0 q10 0 10 -10 m-110 10 h10 m80 0 h10 m-110 -10 v20 m120 0 v-20 m-120 20 v24 m120 0 v-24 m-120 24 q0 10 10 10 m100 0 q10 0 10 -10 m-110 10 h10 m64 0 h10 m0 0 h16 m20 -76 h10 m80 0 h10 m3 0 h-3"></path>
+         <polygon points="353 17 361 13 361 21"></polygon>
+         <polygon points="353 17 345 13 345 21"></polygon>
+      </svg></div>

_includes/sql/v1.1/diagrams/show_sessions.html

@@ -0,0 +1,20 @@
+<div><svg width="372" height="112">
+
+         <polygon points="9 17 1 13 1 21"></polygon>
+         <polygon points="17 17 9 13 9 21"></polygon>
+         <rect x="31" y="3" width="64" height="32" rx="10"></rect>
+         <rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="39" y="21">SHOW</text>
+         <rect x="135" y="35" width="80" height="32" rx="10"></rect>
+         <rect x="133" y="33" width="80" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="143" y="53">CLUSTER</text>
+         <rect x="135" y="79" width="64" height="32" rx="10"></rect>
+         <rect x="133" y="77" width="64" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="143" y="97">LOCAL</text>
+         <rect x="255" y="3" width="90" height="32" rx="10"></rect>
+         <rect x="253" y="1" width="90" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="263" y="21">SESSIONS</text>
+         <path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m20 0 h10 m0 0 h90 m-120 0 h20 m100 0 h20 m-140 0 q10 0 10 10 m120 0 q0 -10 10 -10 m-130 10 v12 m120 0 v-12 m-120 12 q0 10 10 10 m100 0 q10 0 10 -10 m-110 10 h10 m80 0 h10 m-110 -10 v20 m120 0 v-20 m-120 20 v24 m120 0 v-24 m-120 24 q0 10 10 10 m100 0 q10 0 10 -10 m-110 10 h10 m64 0 h10 m0 0 h16 m20 -76 h10 m90 0 h10 m3 0 h-3"></path>
+         <polygon points="363 17 371 13 371 21"></polygon>
+         <polygon points="363 17 355 13 355 21"></polygon>
+      </svg></div>

generate/main.go

@@ -281,7 +281,7 @@ func main() {
 					inline: []string{"opt_transaction"},
 					match:  []*regexp.Regexp{regexp.MustCompile("'COMMIT'|'END'")},
 				},
-				{name: "cancel", stmt: "cancel_query_stmt"},
+				{name: "cancel_query", stmt: "cancel_query_stmt", replace: map[string]string{"a_expr": "query_id"}, unlink: []string{"query_id"}},
 				{name: "create_database_stmt", inline: []string{"opt_encoding_clause"}, replace: map[string]string{"'SCONST'": "encoding"}, unlink: []string{"name", "encoding"}},
 				{
 					name:   "create_index_stmt",
@@ -531,7 +531,10 @@ func main() {
 					unlink: []string{"table_name", "database_name", "user_name"},
 				},
 				{name: "show_index", stmt: "show_stmt", match: []*regexp.Regexp{regexp.MustCompile("'SHOW' 'INDEX'")}, replace: map[string]string{"var_name": "table_name"}, unlink: []string{"table_name"}},
+				{name: "show_jobs", stmt: "show_jobs_stmt"},
 				{name: "show_keys", stmt: "show_stmt", match: []*regexp.Regexp{regexp.MustCompile("'SHOW' 'KEYS'")}},
+				{name: "show_queries", stmt: "show_queries_stmt"},
+				{name: "show_sessions", stmt: "show_sessions_stmt"},
 				{name: "show_tables", stmt: "show_stmt", match: []*regexp.Regexp{regexp.MustCompile("'SHOW' 'TABLES'")}},
 				{name: "show_transaction", stmt: "show_stmt", match: []*regexp.Regexp{regexp.MustCompile("'SHOW' 'TRANSACTION'")}},
 				{name: "show_users", stmt: "show_stmt", match: []*regexp.Regexp{regexp.MustCompile("'SHOW' 'USERS'")}},

v1.1/cancel-query.md

@@ -1,29 +1,76 @@
 ---
 title: CANCEL QUERY
-summary: Cancel a running query
+summary: The CANCEL QUERY statement cancels a running SQL query.
 toc: false
 ---
 
-The `CANCEL QUERY` [statement](sql-statements.html) cancels a running query.
-
-{{site.data.alerts.callout_danger}}<em>Documentation coming soon</em>.{{site.data.alerts.end}}
+<span class="version-tag">New in v1.1:</span> The `CANCEL QUERY` [statement](sql-statements.html) cancels a running SQL query.
 
 <div id="toc"></div>
 
-## Synopsis
+## Considerations
 
-{% include sql/{{ page.version.version }}/diagrams/cancel.html %}
+- Schema changes (statements beginning with <code>ALTER</code>) cannot currently be cancelled. However, to monitor the progress of schema changes, you can use <a href="show-jobs.html"><code>SHOW JOBS</code></a>.
+- In rare cases where a query is close to completion when a cancellation request is issued, the query may run to competion.
 
 ## Required Privileges
 
-`root` can cancel any query running on the cluster.
+The `root` user can cancel any currently active queries, whereas non-`root` users cancel only their own currently active queries.
+
+## Synopsis
 
-Other users can cancel only queries they executed.
+{% include sql/{{ page.version.version }}/diagrams/cancel_query.html %}
 
 ## Parameters
 
+Parameter | Description
+----------|------------
+`query_id` | The ID of the query to cancel, or a [`SELECT`](select.html) statement that returns the ID of the query to cancel.
+
+## Response
+
+When a query is successfully cancelled, CockoachDB sends a `query execution canceled` error to the client that issued the query.
+
+- If the canceled query was a single, standalone statement, no further action is required by the client.
+- If the canceled query was part of a larger, multi-statement [transaction](transactions.html), the client should then issue a [`ROLLBACK`](rollback-transaction.html) statement.
+
 ## Examples
 
+### Cancel a Query via the Query ID
+
+In this example, we use the [`SHOW QUERIES`](show-queries.html) statement to get the ID of a query and then pass the ID into the `CANCEL QUERY` statement:
+
+~~~ sql
+> SHOW QUERIES;
+~~~
+
+~~~
++----------------------------------+---------+----------+----------------------------------+----------------------------------+--------------------+------------------+-------------+-----------+
+|             query_id             | node_id | username |              start               |              query               |   client_address   | application_name | distributed |   phase   |
++----------------------------------+---------+----------+----------------------------------+----------------------------------+--------------------+------------------+-------------+-----------+
+| 14dacc1f9a781e3d0000000000000001 |       2 | mroach   | 2017-08-10 14:08:22.878113+00:00 | SELECT * FROM test.kv ORDER BY k | 192.168.0.72:56194 | test_app         | false       | executing |
++----------------------------------+---------+----------+----------------------------------+----------------------------------+--------------------+------------------+-------------+-----------+
+| 14dacc206c47a9690000000000000002 |       2 | root     | 2017-08-14 19:11:05.309119+00:00 | SHOW CLUSTER QUERIES             | 127.0.0.1:50921    |                  | NULL        | preparing |
++----------------------------------+---------+----------+----------------------------------+----------------------------------+--------------------+------------------+-------------+-----------+
+~~~
+
+~~~ sql
+> CANCEL QUERY '14dacc1f9a781e3d0000000000000001';
+~~~
+
+### Cancel a Query via a Nested `SELECT` Statement
+
+In this example, we nest a [`SELECT`](select.html) statement that retrieves the ID of a query inside the `CANCEL QUERY` statement:
+
+~~~ sql
+> CANCEL QUERY (SELECT query_id FROM [SHOW CLUSTER QUERIES]
+      WHERE client_address = '192.168.0.72:56194'
+          AND username = 'mroach'
+          AND query = 'SELECT * FROM test.kv ORDER BY k');
+~~~
+
 ## See Also
 
+- [Manage Long-Running Queries](manage-long-running-queries.html)
+- [`SHOW QUERIES`](show-queries.html)
 - [SQL Statements](sql-statements.html)

v1.1/debug-and-error-logs.md

@@ -16,8 +16,6 @@ As a command generates messages, CockroachDB uses the [command](#commands)'s [lo
 
 Each node's logs detail only the internal activity of that node without visibility into the behavior of other nodes in the cluster. When troubleshooting, this means that you must identify the node where the problem occurred or [collect the logs from all active nodes in your cluster](debug-zip.html).
 
-{{site.data.alerts.callout_info}}You can also <a href="#log-queries">log queries</a> your cluster receives.{{site.data.alerts.end}}
-
 ### Commands
 
 All [`cockroach` commands](cockroach-commands.html) support logging. However, it's important to note:
@@ -93,56 +91,6 @@ By default, commands besides `cockroach start` discard messages with the `INFO`
 
 The `--log-backtrace-at`, `--verbosity`, and `--v` flags are intended for internal debugging by CockroachDB contributors.
 
-## Log Queries
-
-To help troubleshoot [query performance issues](query-behavior-troubleshooting.html#performance-issues), you can use [cluster-wide settings](cluster-settings.html) to enable logging for long-running SQL transactions or all queries, regardless of time.
-
-{{site.data.alerts.callout_danger}}These settings makes <em>all</em> queries slower and causes nodes to consume more memory. You should <a href="#disable-query-logging">disable query logging</a> as soon as you're done troubleshooting the query's issues.{{site.data.alerts.end}}
-
-### Enable Query Logging
-
-- **Long-running transactions**:
-
-    ~~~ sql
-    > SET CLUSTER SETTING sql.trace.txn.enable_threshold = '[time]';
-    ~~~
-
-    The `[time]` parameter accepts common time specifiers, such as `100ms` or `2s`.
-
-- **All queries**:
-
-    ~~~ sql
-    > SET CLUSTER SETTING sql.trace.log_statement_execute = true;
-    ~~~
-
-### Details
-
-After you enable query logging, whenever nodes process SQL statements, they generate messages with an `INFO` [severity level](#severity-levels).
-
-By default, these messages will get [written to files](#write-to-file), but are ultimate handled by whatever logging behavior you set for [`cockroach start`](start-a-node.html#logging).
-
-### Improve Query Performance
-
-After finding which queries are slow, use [`EXPLAIN`](explain.html) to examine them. It's possible that the query is slow because it performs a full-table scan. In these cases, you can likely improve the query's performance by [adding an index](create-index.html).
-
-*(More guidance around query performance optimization forthcoming.)*
-
-### Disable Query Logging
-
-Once you're done troubleshooting, you should disable query logging to prevent it from unnecessarily consuming resources.
-
-- **Long-running transactions**:
-
-    ~~~ sql
-    > SET CLUSTER SETTING sql.trace.txn.enable_threshold = '0s';
-    ~~~
-
-- **All queries**:
-
-    ~~~ sql
-    > SET CLUSTER SETTING sql.trace.log_statement_execute = false;
-    ~~~
-
 ## See Also
 
 - [Troubleshooting Overview](troubleshooting-overview.html)