transaction

Documentation

Index

• Constants
• Variables
• func Transact(db *gorm.DB, operation func(tx *gorm.DB) error) (err error)
• func TransactWithDefaultRetry(db *gorm.DB, operation func(tx *gorm.DB) error) error
• func TransactWithOptions(db *gorm.DB, txOpts *sql.TxOptions, operation func(tx *gorm.DB) error) (err error)
• func TransactWithRetry(db *gorm.DB, retry RetryOptions, operation func(tx *gorm.DB) error) error
• func TransactWithRetryAndOptions(db *gorm.DB, txOpts *sql.TxOptions, retry RetryOptions, ...) error
• type BackOffFunc
• type RetryOptions
• type RollbackError
  • func (r *RollbackError) Cause() error
  • func (r *RollbackError) Error() string
  • func (r *RollbackError) Unwrap() error

Constants

const (
	// DefaultInitialBackoff configures the initial backoff interval.
	DefaultInitialBackOff = 10 * time.Millisecond
	// DefaultMaxBackoff configures the maximum backoff interval.
	DefaultMaxBackOff = 1 * time.Second
	// DefaultBackOffFactor configues the factor the previous backoff interval will be multiplied by
	// to get the next backoff.
	DefaultBackOffFactor = 2
)

Variables

var DefaultIsRetryable = retryIfApplicable

DefaultIsRetryable configures the default function for determining whether the error returned from the operation is retryable. By default, applicable errors are retryable. A RollbackError is never retryable..

var DefaultMaxRetries = 1

DefaultMaxRetries configures the default number of max retries attempted by TransactWithRetry.

Functions

func Transact

func Transact(db *gorm.DB, operation func(tx *gorm.DB) error) (err error)

Transact executes the operation inside a transaction, committing the transaction on completion. If the operation returns an error or panic, the transaction will be rolled back, returning the original error or propagating the original panic. If the rollback caused by an error also receives an error, a RollbackError will be returned. If the rollback caused by a panic returns an error, the error message and original panic merged and propagated as a new panic.

func TransactWithDefaultRetry

func TransactWithDefaultRetry(db *gorm.DB, operation func(tx *gorm.DB) error) error

TransactWithDefaultRetry runs the operation using Transact, performing retries according to RetryOptions. If all retries fail, the error from the last attempt will be returned. If a rollback fails, no further attempts will be made and the RollbackError will be returned.

Since the transaction operation may be executed multiple times, it is important that any mutations it applies to application state (outside the database) be idempotent.

func TransactWithOptions

func TransactWithOptions(db *gorm.DB, txOpts *sql.TxOptions, operation func(tx *gorm.DB) error) (err error)

TransactWithOptions executes the operation inside a transaction, committing the transaction on completion. If the operation returns an error or panic, the transaction will be rolled back, returning the original error or propagating the original panic. If the rollback caused by an error also receives an error, a RollbackError will be returned. If the rollback caused by a panic returns an error, the error message and original panic merged and propagated as a new panic.

The provided TxOptions is optional and may be nil if defaults should be used. If a non-default isolation level is used that the driver doesn't support, an error will be returned.

func TransactWithRetry

func TransactWithRetry(db *gorm.DB, retry RetryOptions, operation func(tx *gorm.DB) error) error

TransactWithRetry runs the operation using Transact, performing retries according to RetryOptions. If all retries fail, the error from the last attempt will be returned. If a rollback fails, no further attempts will be made and the RollbackError will be returned.

Since the transaction operation may be executed multiple times, it is important that any mutations it applies to application state (outside the database) be idempotent.

func TransactWithRetryAndOptions

func TransactWithRetryAndOptions(db *gorm.DB, txOpts *sql.TxOptions, retry RetryOptions, operation func(tx *gorm.DB) error) error

TransactWithRetryAndOptions runs the operation using Transact, performing retries according to RetryOptions. If all retries fail, the error from the last attempt will be returned. If a rollback fails, no further attempts will be made and the RollbackError will be returned.

Since the transaction operation may be executed multiple times, it is important that any mutations it applies to application state (outside the database) be idempotent.

The provided TxOptions is optional and may be nil if defaults should be used. If a non-default isolation level is used that the driver doesn't support, an error will be returned.

Types

type BackOffFunc

type BackOffFunc func() time.Duration

BackOffFunc is a function called on each retry attempt. It should return a time.Duration to wait before making the next attempt. If a negative time.Duration is returned, retries will be immediately aborted.

type RetryOptions

type RetryOptions struct {
	// MaxRetries configures how many attempts will be made to complete the operation when a retryable error is
	// encountered. The default is DefaultMaxRetries. If set to a negative number, math.MaxInt32 attempts will be made.
	MaxRetries int
	// BackOff is called on each retry, and should return a time.Duration indicating how long to wait before the next
	// attempt. The default is an exponential backoff based on the values of DefaultInitialBackOff, DefaultMaxBackOff,
	// and DefaultBackOffFactor. If a negative Duration is returned by NextBackOff(), retries will be aborted.
	//
	// Most backoff implementations are compatible, including github.com/cenkalti/backoff and
	// github.com/jpillora/backoff.
	BackOff func() time.Duration
	// IsRetryable determines whether the error from the operation should be retried. Return true to retry.
	IsRetryable func(err error) bool
	// Sleep is an optional value to be used for mocking out time.Sleep() for testing. If set, backoff wait
	// will use this function instead of time.Sleep().
	Sleep func(duration time.Duration)
}

RetryOptions controls how TransactWithRetry behaves.

type RollbackError

type RollbackError struct {
	// The original error that the operation returned.
	OriginalErr error
	// The error returned by sql.Tx.Rollback()
	Err error
}

RollbackError is the error returned if the transaction operation returned an error, and the rollback automatically attempted also returns an error.

func (*RollbackError) Cause

func (r *RollbackError) Cause() error

Cause returns the OriginalErr.

func (*RollbackError) Error

func (r *RollbackError) Error() string

Error returns a formatted error message containing both the OriginalErr and RollbackError.

func (*RollbackError) Unwrap

func (r *RollbackError) Unwrap() error

Unwrap returns the OriginalErr.