Merge pull request #1296 from cockroachdb/rollback

Updates to ROLLBACK docs

Author: jseldess

_includes/sql/diagrams/rollback_transaction.html

@@ -1,16 +1,22 @@
-<svg width="302" height="36">
+<svg width="518" height="68">
 
          <polygon points="9 17 1 13 1 21"></polygon>
          <polygon points="17 17 9 13 9 21"></polygon>
          <rect x="31" y="3" width="92" height="32" rx="10"></rect>
          <rect x="29" y="1" width="92" height="32" class="terminal" rx="10"></rect>
          <text class="terminal" x="39" y="21">ROLLBACK</text>
-         <a xlink:href="sql-grammar.html#opt_to_savepoint" xlink:title="opt_to_savepoint">
-            <rect x="143" y="3" width="132" height="32"></rect>
-            <rect x="141" y="1" width="132" height="32" class="nonterminal"></rect>
-            <text class="nonterminal" x="151" y="21">opt_to_savepoint</text>
-         </a>
-         <path class="line" d="m17 17 h2 m0 0 h10 m92 0 h10 m0 0 h10 m132 0 h10 m3 0 h-3"></path>
-         <polygon points="293 17 301 13 301 21"></polygon>
-         <polygon points="293 17 285 13 285 21"></polygon>
+         <rect x="163" y="35" width="38" height="32" rx="10"></rect>
+         <rect x="161" y="33" width="38" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="171" y="53">TO</text>
+         <rect x="221" y="35" width="98" height="32" rx="10"></rect>
+         <rect x="219" y="33" width="98" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="229" y="53">SAVEPOINT</text>
+         
+            <rect x="339" y="35" width="132" height="32"></rect>
+            <rect x="337" y="33" width="132" height="32" class="nonterminal"></rect>
+            <text class="nonterminal" x="347" y="53">cockroach_restart</text>
+         
+         <path class="line" d="m17 17 h2 m0 0 h10 m92 0 h10 m20 0 h10 m0 0 h318 m-348 0 h20 m328 0 h20 m-368 0 q10 0 10 10 m348 0 q0 -10 10 -10 m-358 10 v12 m348 0 v-12 m-348 12 q0 10 10 10 m328 0 q10 0 10 -10 m-338 10 h10 m38 0 h10 m0 0 h10 m98 0 h10 m0 0 h10 m132 0 h10 m23 -32 h-3"></path>
+         <polygon points="509 17 517 13 517 21"></polygon>
+         <polygon points="509 17 501 13 501 21"></polygon>
       </svg>

generate/main.go

@@ -397,7 +397,14 @@ func main() {
 				{name: "rename_index", stmt: "rename_stmt", match: []*regexp.Regexp{regexp.MustCompile("'ALTER' 'INDEX'")}, inline: []string{"table_name_with_index"}, replace: map[string]string{"qualified_name": "table_name", "'@' name": "'@' index_name"}, unlink: []string{"table_name", "index_name"}},
 				{name: "rename_table", stmt: "rename_stmt", match: []*regexp.Regexp{regexp.MustCompile("'ALTER' 'TABLE' .* 'RENAME' 'TO'")}},
 				{name: "revoke_stmt", inline: []string{"privileges", "privilege_list", "privilege", "targets", "grantee_list"}},
-				{name: "rollback_transaction", stmt: "transaction_stmt", inline: []string{"opt_transaction"}, match: []*regexp.Regexp{regexp.MustCompile("'ROLLBACK'")}},
+				{
+					name: "rollback_transaction",
+					stmt: "transaction_stmt",
+					inline: []string{"opt_to_savepoint"},
+					match: []*regexp.Regexp{regexp.MustCompile("'ROLLBACK'")},
+					replace: map[string]string{"'TRANSACTION'": "", "'TO'": "'TO' 'SAVEPOINT'","savepoint_name": "cockroach_restart"},
+					unlink: []string{"cockroach_restart"},
+				},
 				{name: "savepoint_stmt", inline: []string{"savepoint_name"}},
 				{
 					name:   "select_stmt",

rollback-transaction.md

@@ -6,7 +6,7 @@ toc: false
 
 The `ROLLBACK` [statement](sql-statements.html) aborts the current [transaction](transactions.html), discarding all updates made by statements included in the transaction.
 
-When using [client-side transaction retries](transactions.html#client-side-transaction-retries), use `ROLLBACK TO SAVEPOINT cockroach_restart` to handle transaction that need to be retried (identified via the `40001` error code or `retry transaction` string in the error message), and then re-execute the statements in the transaction.
+When using [client-side transaction retries](transactions.html#client-side-transaction-retries), use `ROLLBACK TO SAVEPOINT cockroach_restart` to handle a transaction that needs to be retried (identified via the `40001` error code or `retry transaction` string in the error message), and then re-execute the statements you want the transaction to contain.
 
 <div id="toc"></div>
 
@@ -22,13 +22,13 @@ No [privileges](privileges.html) are required to rollback a transaction. However
 
 | Parameter | Description |
 |-----------|-------------|
-| `TO cockroach_restart` | If using [client-side transaction retries](transactions.html#client-side-transaction-retries), retry the transaction. You should execute this statement when a transaction returns a `40001` / `retry transaction` error. |
+| `TO SAVEPOINT cockroach_restart` | If using [client-side transaction retries](transactions.html#client-side-transaction-retries), retry the transaction. You should execute this statement when a transaction returns a `40001` / `retry transaction` error. |
 
 ## Example
 
 ### Rollback a Transaction
 
-Typically, your application conditionally executes rollbacks but you can see their behavior by using `ROLLBACK` instead of `COMMIT` directly through SQL.
+Typically, your application conditionally executes rollbacks, but you can see their behavior by using `ROLLBACK` instead of `COMMIT` directly through SQL.
 
 ~~~ sql
 > SELECT * FROM accounts;
@@ -59,10 +59,10 @@ Typically, your application conditionally executes rollbacks but you can see the
 
 ### Retry a Transaction
 
-To use [client-side transaction retries](transactions.html#client-side-transaction-retries), your application must execute `ROLLBACK TO cockroach_restart` after detecting a `40001` / `retry transaction` error.
+To use [client-side transaction retries](transactions.html#client-side-transaction-retries), your application must execute `ROLLBACK TO SAVEPOINT cockroach_restart` after detecting a `40001` / `retry transaction` error.
 
 ~~~ sql
-> ROLLBACK TO cockroach_restart;
+> ROLLBACK TO SAVEPOINT cockroach_restart;
 ~~~
 
 For examples of retrying transactions in your application, check out the transaction code samples in our [Build an App with CockroachDB](build-an-app-with-cockroachdb.html) tutorials.

savepoint.md

@@ -9,7 +9,7 @@ The `SAVEPOINT cockroach_restart` statement defines the intent to retry [transac
 {{site.data.alerts.callout_danger}}CockroachDB’s <code>SAVEPOINT</code> implementation only supports the <code>cockroach_restart</code> savepoint and does not support all savepoint functionality, such as nested transactions.{{site.data.alerts.end}}
 
 <div id="toc"></div>
- 
+
 ## Synopsis
 
 {% include sql/diagrams/savepoint.html %}
@@ -38,7 +38,7 @@ After you `BEGIN` the transaction, you must create the savepoint to identify tha
 > COMMIT;
 ~~~
 
-When using `SAVEPOINT`, your application must also include functions to execute retries with [`ROLLBACK TO cockroach_restart`](rollback-transaction.html#retry-a-transaction).
+When using `SAVEPOINT`, your application must also include functions to execute retries with [`ROLLBACK TO SAVEPOINT cockroach_restart`](rollback-transaction.html#retry-a-transaction).
 
 ## See Also
 

transactions.md

@@ -21,15 +21,15 @@ Each of the following SQL statements control transactions in some way.
 | [`SAVEPOINT cockroach_restart`](savepoint.html) | Declare the transaction as [retryable](#client-side-transaction-retries). This lets you retry the transaction if it doesn't succeed because a higher priority transaction concurrently or recently accessed the same values. |
 | [`RELEASE SAVEPOINT cockroach_restart`](release-savepoint.html) | Commit a [retryable transaction](#client-side-transaction-retries). |
 | [`COMMIT`](commit-transaction.html) | Commit a non-retryable transaction or clear the connection after committing a retryable transaction. |
-| [`ROLLBACK cockroach_restart`](rollback-transaction.html) | Handle [retryable errors](#error-handling) by rolling back a transaction's changes and increasing its priority. |
+| [`ROLLBACK TO SAVEPOINT cockroach_restart`](rollback-transaction.html) | Handle [retryable errors](#error-handling) by rolling back a transaction's changes and increasing its priority. |
 | [`ROLLBACK`](rollback-transaction.html) | Abort a transaction and roll the database back to its state before the transaction began. |
 | [`SHOW TRANSACTION`](show-transaction.html) | Retrieve a transaction's [priority](#transaction-priorities) or [isolation level](#isolation-levels). |
 
 ## Syntax
 
 In CockroachDB, a transaction is set up by surrounding SQL statements with the [`BEGIN`](begin-transaction.html) and [`COMMIT`](commit-transaction.html) statements.
 
-To use [client-side transaction retries](#client-side-transaction-retries), you should also include the `SAVEPOINT cockroach_restart`, `ROLLBACK TO cockroach_restart` and `RELEASE SAVEPOINT` statements.
+To use [client-side transaction retries](#client-side-transaction-retries), you should also include the `SAVEPOINT cockroach_restart`, `ROLLBACK TO SAVEPOINT cockroach_restart` and `RELEASE SAVEPOINT` statements.
 
 ~~~ sql
 > BEGIN;
@@ -144,9 +144,9 @@ Implementing client-side retries requires three statements:
 
 - [`SAVEPOINT cockroach_restart`](savepoint.html) declares the client's intent to retry the transaction if there are contention errors. It must be executed after `BEGIN` but before the first statement that manipulates a database.
 
-- [`ROLLBACK TO cockroach_restart`](rollback-transaction.html#retry-a-transaction) is used when your application detects `40001` / `retry transaction` errors. It provides you a chance to "retry" the transaction by rolling the database's state back to the beginning of the transaction and increasing the transaction's priority.
+- [`ROLLBACK TO SAVEPOINT cockroach_restart`](rollback-transaction.html#retry-a-transaction) is used when your application detects `40001` / `retry transaction` errors. It provides you a chance to "retry" the transaction by rolling the database's state back to the beginning of the transaction and increasing the transaction's priority.
 
-  After issuing `ROLLBACK TO cockroach_restart`, you must issue any statements you want the transaction to contain. Typically, this means recalculating values and reissuing a similar set of statements to the previous attempt.
+  After issuing `ROLLBACK TO SAVEPOINT cockroach_restart`, you must issue any statements you want the transaction to contain. Typically, this means recalculating values and reissuing a similar set of statements to the previous attempt.
 
 - [`RELEASE SAVEPOINT cockroach_restart`](release-savepoint.html) commits the transaction. At this point, CockroachDB checks to see if the transaction contends with others for access to the same values; the highest priority transaction succeeds, and the others return `40001` / `retry transaction` errors.