> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Client-side Transaction Retries

This page has instructions for authors of [database drivers and ORMs](https://docs.cockroachlabs.com/docs/stable/install-client-drivers.md) who would like to implement client-side retries in their database driver or ORM for maximum efficiency and ease of use by application developers.

> [!NOTE]
>
> If you are an application developer who needs to implement an application-level retry loop, see the [client-side retry handling example](https://docs.cockroachlabs.com/docs/stable/transaction-retry-error-example.md).

## Overview

To improve the performance of transactions that fail due to [contention](https://docs.cockroachlabs.com/docs/stable/performance-best-practices-overview.md#transaction-contention), CockroachDB includes a set of statements (listed below) that let you retry those transactions. Retrying transactions using these statements has the benefit that when you use savepoints, you "hold your place in line" between attempts. Without savepoints, you're starting from scratch every time.

## How transaction retries work

A retryable transaction goes through the process described below, which maps to the following SQL statements:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> BEGIN;                                  -- #1
> SAVEPOINT cockroach_restart;            -- #2
-- ... various transaction statements ... -- #3
> RELEASE SAVEPOINT cockroach_restart;    -- #5 (Or #4, ROLLBACK, in case of retry error)
> COMMIT;
```

1. The transaction starts with the [`BEGIN`](https://docs.cockroachlabs.com/docs/stable/begin-transaction) statement.

2. The [`SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/savepoint) statement shown here is a [retry savepoint](#retry-savepoints); that is, it declares the intention to retry the transaction in the case of contention errors. It must be executed after [`BEGIN`](https://docs.cockroachlabs.com/docs/stable/begin-transaction), but before the first statement that manipulates a database. Although [nested transactions](https://docs.cockroachlabs.com/docs/stable/savepoint.md#savepoints-for-nested-transactions) are supported in versions of CockroachDB 20.1 and later, a retry savepoint must be the outermost savepoint in a transaction.

3. The statements in the transaction are executed.

4. If a statement returns a retry error (identified via the `40001` error code or `"restart transaction"` string at the start of the error message), you can issue the [`ROLLBACK TO SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/rollback-transaction) statement to restart the transaction. Alternately, the original [`SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/savepoint) statement can be reissued to restart the transaction.

   You must now issue the statements in the transaction again.

   In cases where you do not want the application to retry the transaction, you can issue [`ROLLBACK`](https://docs.cockroachlabs.com/docs/stable/rollback-transaction) at this point. Any other statements will be rejected by the server, as is generally the case after an error has been encountered and the transaction has not been closed.

5. Once the transaction executes all statements without encountering contention errors, execute [`RELEASE SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/release-savepoint) to commit the changes. If this succeeds, all changes made by the transaction become visible to subsequent transactions and are guaranteed to be durable if a crash occurs.

   In some cases, the [`RELEASE SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/release-savepoint) statement itself can fail with a retry error, mainly because transactions in CockroachDB only realize that they need to be restarted when they attempt to commit. If this happens, the retry error is handled as described in step 4.

## Retry savepoints

A savepoint defined with the name `cockroach_restart` is a "retry savepoint" and is used to implement advanced client-side transaction retries. A retry savepoint differs from a [savepoint for nested transactions](https://docs.cockroachlabs.com/docs/stable/savepoint.md#savepoints-for-nested-transactions) as follows:

* It must be the outermost savepoint in the transaction.
* After a successful [`RELEASE`](https://docs.cockroachlabs.com/docs/stable/release-savepoint), a retry savepoint does not allow further use of the transaction. The next statement must be a [`COMMIT`](https://docs.cockroachlabs.com/docs/stable/commit-transaction).
* It cannot be nested. Issuing `SAVEPOINT cockroach_restart` two times in a row only creates a single savepoint marker (this can be verified with [`SHOW SAVEPOINT STATUS`](https://docs.cockroachlabs.com/docs/stable/show-savepoint-status)). Issuing `SAVEPOINT cockroach_restart` after `ROLLBACK TO SAVEPOINT cockroach_restart` reuses the marker instead of creating a new one.

Note that you can [customize the retry savepoint name](#customizing-the-retry-savepoint-name) to something other than `cockroach_restart` with a session variable if you need to.

## Customizing the retry savepoint name

Set the `force_savepoint_restart` [session variable](https://docs.cockroachlabs.com/docs/stable/set-vars.md#supported-variables) to `true` to enable using a custom name for the [retry savepoint](https://docs.cockroachlabs.com/docs/stable/advanced-client-side-transaction-retries.md#retry-savepoints).

Once this variable is set, the [`SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/savepoint) statement will accept any name for the retry savepoint, not just `cockroach_restart`. In addition, it causes every savepoint name to be equivalent to `cockroach_restart`, therefore disallowing the use of [nested transactions](https://docs.cockroachlabs.com/docs/stable/transactions.md#nested-transactions).

This feature exists to support applications that want to use the [advanced client-side transaction retry protocol](https://docs.cockroachlabs.com/docs/stable/advanced-client-side-transaction-retries.md), but cannot customize the name of savepoints to be `cockroach_restart`.  For example, this may be necessary because you are using an ORM that requires its own names for savepoints.

## Examples

For examples showing how to use [`SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/savepoint) and the other statements described on this page to implement library support for a programming language, see the following:

* [Build a Java app with CockroachDB](https://docs.cockroachlabs.com/docs/stable/build-a-java-app-with-cockroachdb.md), in particular the logic in the `runSQL` method.
* The source code of the [sqlalchemy-cockroachdb](https://github.com/cockroachdb/sqlalchemy-cockroachdb) adapter for SQLAlchemy.

## See also

* [Transactions](https://docs.cockroachlabs.com/docs/stable/transactions.md)
* [`BEGIN`](https://docs.cockroachlabs.com/docs/stable/begin-transaction)
* [`COMMIT`](https://docs.cockroachlabs.com/docs/stable/commit-transaction)
* [`ROLLBACK`](https://docs.cockroachlabs.com/docs/stable/rollback-transaction)
* [`SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/savepoint)
* [`RELEASE SAVEPOINT`](https://docs.cockroachlabs.com/docs/stable/release-savepoint)
* [`SHOW`](https://docs.cockroachlabs.com/docs/stable/show-vars)
* [DB Console Transactions Page](https://docs.cockroachlabs.com/docs/stable/ui-transactions-page.md)
* [CockroachDB Architecture: Transaction Layer](https://docs.cockroachlabs.com/docs/stable/architecture/transaction-layer.md)