Documentation
¶
Index ¶
- Variables
- func Do(ctx context.Context, trm Trm, level pgx.TxIsoLevel, ...) error
- func DoAndRet[T any](ctx context.Context, mgr Trm, level pgx.TxIsoLevel, ...) (ret T, err error)
- func DoReadCommitted(ctx context.Context, manager Trm, fn func(ctx context.Context) error, ...) error
- func DoReadCommittedRet[T any](ctx context.Context, manager Trm, f func(ctx context.Context) (T, error), ...) (ret T, err error)
- func DoReadUncommitted(ctx context.Context, manager Trm, fn func(ctx context.Context) error, ...) error
- func DoReadUncommittedRet[T any](ctx context.Context, manager Trm, f func(ctx context.Context) (T, error), ...) (ret T, err error)
- func DoRepeatableRead(ctx context.Context, manager Trm, fn func(ctx context.Context) error, ...) error
- func DoRepeatableReadRet[T any](ctx context.Context, manager Trm, f func(ctx context.Context) (T, error), ...) (ret T, err error)
- func DoSerializable(ctx context.Context, manager Trm, fn func(ctx context.Context) error, ...) error
- func DoSerializableRet[T any](ctx context.Context, manager Trm, f func(ctx context.Context) (T, error), ...) (ret T, err error)
- func DoSettings(ctx context.Context, trm Trm, settings *trmpgx.Settings, ...) error
- func IsRetryable(err error) bool
- func NewSettings(level pgx.TxIsoLevel, opts ...settings.Opt) *trmpgx.Settings
- func ReadCommitted(opts ...settings.Opt) *trmpgx.Settings
- func ReadUncommitted(opts ...settings.Opt) *trmpgx.Settings
- func RepeatableRead(opts ...settings.Opt) *trmpgx.Settings
- func Serializable(opts ...settings.Opt) *trmpgx.Settings
- type Backoff
- type BackoffFactory
- type DB
- type DbOption
- type Opt
- type RetryPolicy
- type Trm
Constants ¶
This section is empty.
Variables ¶
var DefaultBackoff = NewExpBackoff(5*time.Millisecond, time.Second, true)
DefaultBackoff is exponential (5ms base, 1s cap) with full jitter.
var DefaultRetryPolicy = RetryPolicy{ MaxAttempts: 5, Backoff: DefaultBackoff, }
DefaultRetryPolicy is a sane starting point for serializable workloads.
Functions ¶
func DoReadCommitted ¶
func DoReadCommittedRet ¶
func DoReadUncommitted ¶
func DoReadUncommittedRet ¶
func DoRepeatableRead ¶
func DoRepeatableReadRet ¶
func DoSerializable ¶
func DoSerializableRet ¶
func DoSettings ¶
func IsRetryable ¶ added in v1.1.0
IsRetryable reports whether err is a transient Postgres error that warrants retrying the entire transaction: serialization_failure (40001) or deadlock_detected (40P01).
func NewSettings ¶
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
}
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
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.