crdb

func Execute ¶

func Execute(fn func() error) (err error)

Execute runs fn and retries it as needed. It is used to add retry handling to the execution of a single statement. If a multi-statement transaction is being run, use ExecuteTx instead.

Retry handling for individual statements (implicit transactions) is usually performed automatically on the CockroachDB SQL gateway. As such, use of this function is generally not necessary. The exception to this rule is that automatic retries for individual statements are disabled once CockroachDB begins streaming results for the statements back to the client. By default, result streaming does not begin until the size of the result being produced for the client, including protocol overhead, exceeds 16KiB. As long as the results of a single statement or batch of statements are known to stay clear of this limit, the client does not need to worry about retries and should not need to use this function.

For more information about automatic transaction retries in CockroachDB, see https://cockroachlabs.com/docs/stable/transactions.html#automatic-retries.

NOTE: the supplied fn closure should not have external side effects beyond changes to the database.

fn must take care when wrapping errors returned from the database driver with additional context. For example, if the SELECT statement fails in the following snippet, the original retryable error will be masked by the call to fmt.Errorf, and the transaction will not be automatically retried.

crdb.Execute(func () error {
    rows, err := db.QueryContext(ctx, "SELECT ...")
    if err != nil {
        return fmt.Errorf("scanning row: %s", err)
    }
    defer rows.Close()
    for rows.Next() {
        // ...
    }
    if err := rows.Err(); err != nil {
        return fmt.Errorf("scanning row: %s", err)
    }
    return nil
})

Instead, add context by returning an error that implements either: - a `Cause() error` method, in the manner of github.com/pkg/errors, or - an `Unwrap() error` method, in the manner of the Go 1.13 standard library.

To achieve this, you can implement your own error type, or use `errors.Wrap()` from github.com/pkg/errors or github.com/cockroachdb/errors or a similar package, or use go 1.13's special `%w` formatter with fmt.Errorf(), for example fmt.Errorf("scanning row: %w", err).

import "github.com/pkg/errors"

crdb.Execute(func () error {
    rows, err := db.QueryContext(ctx, "SELECT ...")
    if err != nil {
        return errors.Wrap(err, "scanning row")
    }
    defer rows.Close()
    for rows.Next() {
        // ...
    }
    if err := rows.Err(); err != nil {
        return errors.Wrap(err, "scanning row")
    }
    return nil
})

func ExecuteCtx ¶ added in v2.4.0

func ExecuteCtx(ctx context.Context, fn ExecuteCtxFunc, args ...interface{}) (err error)

ExecuteCtx runs fn and retries it as needed, respecting a retry policy obtained from the context. It is used to add configurable retry handling to the execution of a single statement. If a multi-statement transaction is being run, use ExecuteTx instead.

The maximum number of retries can be configured using WithMaxRetries(ctx, n). Setting n=0 allows one attempt with no retries. If the number of retries is exhausted and the last attempt resulted in a retryable error, ExecuteCtx returns a max retries exceeded error wrapping the last retryable error encountered.

Arbitrary retry policies can be configured using WithRetryPolicy(ctx, p).

The fn parameter accepts variadic arguments which are passed through on each retry attempt, allowing for flexible parameterization of the retried operation.

As with Execute, retry handling for individual statements (implicit transactions) is usually performed automatically on the CockroachDB SQL gateway, making use of this function generally unnecessary. However, automatic retries are disabled once result streaming begins (typically when results exceed 16KiB).

NOTE: the supplied fn closure should not have external side effects beyond changes to the database.

fn must take care when wrapping errors returned from the database driver with additional context. To preserve retry behavior, errors should implement either `Cause() error` (github.com/pkg/errors) or `Unwrap() error` (Go 1.13+). For example:

crdb.ExecuteCtx(ctx, func(ctx context.Context, args ...interface{}) error {
    id := args[0].(int)
    rows, err := db.QueryContext(ctx, "SELECT * FROM users WHERE id = $1", id)
    if err != nil {
        return fmt.Errorf("scanning row: %w", err) // uses %w for proper error wrapping
    }
    defer rows.Close()
    // ...
    return nil
}, userID)

func ExecuteInTx ¶

func ExecuteInTx(ctx context.Context, tx Tx, fn func() error) (err error)

ExecuteInTx runs fn inside tx. This method is primarily intended for internal use. See other packages for higher-level, framework-specific ExecuteTx() functions.

*WARNING*: It is assumed that no statements have been executed on the supplied Tx. ExecuteInTx will only retry statements that are performed within the supplied closure (fn). Any statements performed on the tx before ExecuteInTx is invoked will *not* be re-run if the transaction needs to be retried.

fn is subject to the same restrictions as the fn passed to ExecuteTx.

func ExecuteTx ¶

func ExecuteTx(ctx context.Context, db *sql.DB, opts *sql.TxOptions, fn func(*sql.Tx) error) error

ExecuteTx runs fn inside a transaction and retries it as needed. On non-retryable failures, the transaction is aborted and rolled back; on success, the transaction is committed.

There are cases where the state of a transaction is inherently ambiguous: if we err on RELEASE with a communication error it's unclear if the transaction has been committed or not (similar to erroring on COMMIT in other databases). In that case, we return AmbiguousCommitError.

There are cases when restarting a transaction fails: we err on ROLLBACK to the SAVEPOINT. In that case, we return a TxnRestartError.

For more information about CockroachDB's transaction model, see https://cockroachlabs.com/docs/stable/transactions.html.

NOTE: the supplied fn closure should not have external side effects beyond changes to the database.

fn must take care when wrapping errors returned from the database driver with additional context. For example, if the UPDATE statement fails in the following snippet, the original retryable error will be masked by the call to fmt.Errorf, and the transaction will not be automatically retried.

crdb.ExecuteTx(ctx, db, txopts, func (tx *sql.Tx) error {
    if err := tx.ExecContext(ctx, "UPDATE..."); err != nil {
        return fmt.Errorf("updating record: %s", err)
    }
    return nil
})

Instead, add context by returning an error that implements either: - a `Cause() error` method, in the manner of github.com/pkg/errors, or - an `Unwrap() error` method, in the manner of the Go 1.13 standard library.

To achieve this, you can implement your own error type, or use `errors.Wrap()` from github.com/pkg/errors or github.com/cockroachdb/errors or a similar package, or use go 1.13's special `%w` formatter with fmt.Errorf(), for example fmt.Errorf("scanning row: %w", err).

import "github.com/pkg/errors"

crdb.ExecuteTx(ctx, db, txopts, func (tx *sql.Tx) error {
    if err := tx.ExecContext(ctx, "UPDATE..."); err != nil {
        return errors.Wrap(err, "updating record")
    }
    return nil
})

func ExecuteTxGenericTest ¶

func ExecuteTxGenericTest(ctx context.Context, framework WriteSkewTest) error

ExecuteTxGenericTest represents the structure of a test for the ExecuteTx function. The actual database operations are abstracted by framework; the idea is that tests for different frameworks implement that interface and then invoke this test.

The test interleaves two transactions such that one of them will require a restart because of write skew.

func WithMaxRetries ¶ added in v2.2.8

func WithMaxRetries(ctx context.Context, retries int) context.Context

WithMaxRetries configures context so that ExecuteTx retries the transaction up to the specified number of times when encountering retryable errors.

The retries parameter controls retry behavior:

• Positive value (e.g., 10): Retry up to that many times before failing
• 0 (UnlimitedRetries): Retry indefinitely until success or non-retryable error (not recommended in production as it can lead to infinite retry loops)

This is a convenience function that creates a LimitBackoffRetryPolicy with no delay between retries (immediate retries).

Example with limited retries:

ctx := crdb.WithMaxRetries(context.Background(), 10)
err := crdb.ExecuteTx(ctx, db, nil, func(tx *sql.Tx) error {
    // Will retry up to 10 times on retryable errors
    return tx.ExecContext(ctx, "UPDATE ...")
})

Example with unlimited retries (use with caution):

ctx := crdb.WithMaxRetries(context.Background(), 0)
// Will retry indefinitely - ensure you have a context timeout!

To disable retries entirely, use WithNoRetries(ctx) instead.

func WithNoRetries ¶ added in v2.4.3

func WithNoRetries(ctx context.Context) context.Context

WithNoRetries configures context so that ExecuteTx will not retry on retryable errors. The transaction will be attempted exactly once.

This is useful when you want to handle retries manually or when operating in a context where automatic retries are not desired (e.g., in testing, or when implementing custom retry logic).

Example usage:

ctx := crdb.WithNoRetries(context.Background())
err := crdb.ExecuteTx(ctx, db, nil, func(tx *sql.Tx) error {
    // This will execute only once, no automatic retries
    return tx.ExecContext(ctx, "UPDATE ...")
})
if err != nil {
    // Handle error manually, potentially implementing custom retry logic
}

func WithRetryPolicy ¶ added in v2.4.3

func WithRetryPolicy(ctx context.Context, policy RetryPolicy) context.Context

WithRetryPolicy uses an arbitrary retry policy to perform retries.