tx

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

DefaultBackoff is exponential (5ms base, 1s cap) with full jitter.

View Source
var DefaultRetryPolicy = RetryPolicy{
	MaxAttempts: 5,
	Backoff:     DefaultBackoff,
}

DefaultRetryPolicy is a sane starting point for serializable workloads.

Functions

func Do

func Do(
	ctx context.Context,
	trm Trm,
	level pgx.TxIsoLevel,
	fn func(ctx context.Context) error,
	opts ...Opt,
) error

func DoAndRet

func DoAndRet[T any](
	ctx context.Context,
	mgr Trm,
	level pgx.TxIsoLevel,
	f func(ctx context.Context) (T, error),
	opts ...Opt,
) (ret T, err error)

func DoReadCommitted

func DoReadCommitted(
	ctx context.Context,
	manager Trm,
	fn func(ctx context.Context) error,
	opts ...Opt,
) error

func DoReadCommittedRet

func DoReadCommittedRet[T any](
	ctx context.Context,
	manager Trm,
	f func(ctx context.Context) (T, error),
	opts ...Opt,
) (ret T, err error)

func DoReadUncommitted

func DoReadUncommitted(
	ctx context.Context,
	manager Trm,
	fn func(ctx context.Context) error,
	opts ...Opt,
) error

func DoReadUncommittedRet

func DoReadUncommittedRet[T any](
	ctx context.Context,
	manager Trm,
	f func(ctx context.Context) (T, error),
	opts ...Opt,
) (ret T, err error)

func DoRepeatableRead

func DoRepeatableRead(
	ctx context.Context,
	manager Trm,
	fn func(ctx context.Context) error,
	opts ...Opt,
) error

func DoRepeatableReadRet

func DoRepeatableReadRet[T any](
	ctx context.Context,
	manager Trm,
	f func(ctx context.Context) (T, error),
	opts ...Opt,
) (ret T, err error)

func DoSerializable

func DoSerializable(
	ctx context.Context,
	manager Trm,
	fn func(ctx context.Context) error,
	opts ...Opt,
) error

func DoSerializableRet

func DoSerializableRet[T any](
	ctx context.Context,
	manager Trm,
	f func(ctx context.Context) (T, error),
	opts ...Opt,
) (ret T, err error)

func DoSettings

func DoSettings(
	ctx context.Context,
	trm Trm,
	settings *trmpgx.Settings,
	fn func(ctx context.Context) error,
) error

func IsRetryable added in v1.1.0

func IsRetryable(err error) bool

IsRetryable reports whether err is a transient Postgres error that warrants retrying the entire transaction: serialization_failure (40001) or deadlock_detected (40P01).

func NewSettings

func NewSettings(level pgx.TxIsoLevel, opts ...settings.Opt) *trmpgx.Settings

func ReadCommitted

func ReadCommitted(opts ...settings.Opt) *trmpgx.Settings

func ReadUncommitted

func ReadUncommitted(opts ...settings.Opt) *trmpgx.Settings

func RepeatableRead

func RepeatableRead(opts ...settings.Opt) *trmpgx.Settings

func Serializable

func Serializable(opts ...settings.Opt) *trmpgx.Settings

Types

type Backoff added in v1.1.0

type Backoff interface {
	// Next returns the delay before the next retry. ok=false stops retrying.
	Next() (delay time.Duration, ok bool)
}

Backoff yields the delay to wait before each retry. It is stateful: a fresh instance is created per transaction run via BackoffFactory, so it may track the attempt count internally.

The signature matches common Go retry libraries (sethvargo/go-retry, cenkalti/backoff), so an external implementation can be adapted in a few lines without pulling the dependency into pgtx core.

type BackoffFactory added in v1.1.0

type BackoffFactory func() Backoff

BackoffFactory builds a fresh Backoff for a single transaction run.

func NewExpBackoff added in v1.1.0

func NewExpBackoff(base, maxDelay time.Duration, jitter bool) BackoffFactory

NewExpBackoff returns a factory producing an exponential backoff: delay doubles each attempt starting from base, capped at maxDelay (0 = no cap). With jitter the delay is randomized in [0, computed].

type DB

type DB interface {
	// Exec executes the given SQL statement with the provided arguments in the context of the executor.
	//
	// Parameters:
	// - ctx: The context.Context object.
	// - sql: The SQL statement to execute.
	// - arguments: The arguments to be passed to the SQL statement.
	//
	// Returns:
	// - pgconn.CommandTag: The command tag returned by the execution.
	// - error: An error if the execution fails.
	Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)
	// Query executes a SQL query with the provided arguments in the context of the executor.
	//
	// Parameters:
	// - ctx: The context.Context object.
	// - sql: The SQL query to execute.
	// - arguments: The arguments to be passed to the SQL query.
	//
	// Returns:
	// - pgx.Rows: The result of the query.
	// - error: An error if the query execution fails.
	Query(ctx context.Context, sql string, arguments ...interface{}) (pgx.Rows, error)
	// QueryRow executes a SQL query with the provided arguments in the context of the executor,
	// returning a single row result.
	//
	// Parameters:
	// - ctx: The context.Context object.
	// - sql: The SQL query to execute.
	// - arguments: The arguments to be passed to the SQL query.
	//
	// Returns:
	// - pgx.Row: The result of the query as a single row.
	QueryRow(ctx context.Context, sql string, arguments ...interface{}) pgx.Row

	CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, rowSrc pgx.CopyFromSource) (int64, error)

	SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
}

func NewTxDb

func NewTxDb(defaultTr trmpgx.Tr, options ...DbOption) DB

NewTxDb creates a new TxExecutor with the given defaultTr and options.

Parameters: - defaultTr: The default transaction to use. - options: Optional configurations for the TxExecutor.

Returns: - *TxExecutor: The newly created TxExecutor.

type DbOption

type DbOption func(*executor)

func WithCtxGetter

func WithCtxGetter(ctxGetter ctxGetter) DbOption

WithCtxGetter sets the ctxGetter for the TxExecutor.

Parameters: - ctxGetter: The ctxGetter implementation to be used.

Returns: - TxExecutorOption: A function that takes a TxExecutor pointer and sets its ctxGetter field.

type Opt added in v1.1.0

type Opt func(*config)

Opt configures a Do* call: retry behavior and/or pass-through trm settings.

func WithRetry added in v1.1.0

func WithRetry(p RetryPolicy) Opt

WithRetry enables transaction retries with the given policy.

func WithTrmSettings added in v1.1.0

func WithTrmSettings(opts ...settings.Opt) Opt

WithTrmSettings forwards options to the underlying transaction manager (timeouts, propagation, etc.).

type RetryPolicy added in v1.1.0

type RetryPolicy struct {
	// MaxAttempts is the total number of attempts, including the first one.
	// Values <= 1 disable retries. Retrying also stops early if Backoff
	// returns ok=false.
	MaxAttempts int
	// Backoff builds the delay strategy between attempts. nil falls back to
	// DefaultBackoff.
	Backoff BackoffFactory
	// Retryable decides whether err is transient and worth retrying.
	// nil falls back to IsRetryable.
	Retryable func(error) bool
}

RetryPolicy controls how a transaction is retried when it fails with a transient error (serialization failure or deadlock).

Retry re-runs the whole transactional function from scratch in a new transaction. The function MUST therefore be safe to run more than once: non-database side effects (sending mail, mutating external state) will be repeated on every attempt.

Retry only makes sense for top-level transactions. Enabling it on a nested transaction that joins a parent is unsafe: once the parent is aborted, a re-run cannot succeed.

type Trm

type Trm = trm.Manager

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL