trm

Documentation

Overview

Package trm contains of interfaces to programmatic transaction management.

Index

• Variables
• func IsSkippable(err error) bool
• func Skippable(err error) error
• func UnSkippable(err error) error
• type CtxGetter
• type CtxKey
• type Manager
• type NestedTrFactory
• type Propagation
• type Settings
• type TrFactory
• type Transaction
• type СtxManager

Variables

var (
	// ErrTransaction is an error while working with a transaction.
	ErrTransaction = errors.New("transaction")
	// ErrAlreadyClosed occurs if the transaction was closed outside the Manager.
	ErrAlreadyClosed = errTransaction("already closed")

	// ErrBegin occurs when a transaction started with an error.
	ErrBegin = errTransaction("begin")
	// ErrCommit occurs when commit finished with an error.
	ErrCommit = errTransaction("commit")
	// ErrRollback occurs when rollback finished with an error.
	ErrRollback = errTransaction("rollback")

	// ErrNestedBegin occurs when nested transaction started with an error.
	ErrNestedBegin = errNested(ErrBegin, "nested")
	// ErrNestedCommit occurs when nested transaction finished with an error.
	ErrNestedCommit = errNested(ErrCommit, "nested")
	// ErrNestedRollback occurs when rollback nested transaction finished with an error.
	ErrNestedRollback = errNested(ErrRollback, "nested")
)

var (
	// ErrPropagation occurs because of Propagation setting.
	ErrPropagation = errTransaction("propagation")
	// ErrPropagationMandatory occurs when the transaction doesn't exist.
	ErrPropagationMandatory = errNested(ErrPropagation, "mandatory")
	// ErrPropagationNever occurs when the transaction already exists.
	ErrPropagationNever = errNested(ErrPropagation, "never")
)

var ErrSkip = errors.New("skippable")

ErrSkip marks error to skip rollback for transaction because of inside error.

Functions

func IsSkippable

func IsSkippable(err error) bool

IsSkippable checks that the error is ErrSkip.

func Skippable

func Skippable(err error) error

Skippable marks error as ErrSkip.

func UnSkippable

func UnSkippable(err error) error

UnSkippable removes ErrSkip from error.

Types

type CtxGetter

type CtxGetter func(ctx context.Context) Transaction

CtxGetter gets Transaction from context.Context.

type CtxKey

type CtxKey interface{}

CtxKey is a type to identify trm.Transaction in a context.Context.

type Manager

type Manager interface {
	// Do processes a transaction inside a closure.
	Do(context.Context, func(ctx context.Context) error) error
	// DoWithSettings processes a transaction inside a closure with custom trm.Settings.
	DoWithSettings(context.Context, Settings, func(ctx context.Context) error) error
}

Manager manages a transaction from Begin to Commit or Rollback.

type NestedTrFactory

type NestedTrFactory interface {
	Begin(ctx context.Context, s Settings) (context.Context, Transaction, error)
}

NestedTrFactory creates nested Transaction.

type Propagation

type Propagation int8

Propagation is a type for transaction propagation rules.

const (
	// PropagationRequired supports a current transaction, create a new one if none exists. This is default setting.
	PropagationRequired Propagation = iota
	// PropagationNested executes within a nested transaction
	// if a current transaction exists, create a new one if none exists.
	PropagationNested
	// PropagationsMandatory supports a current transaction, throws an exception if none exists.
	PropagationsMandatory
	// PropagationNever executes non-transactionally, throws an exception if a transaction exists.
	PropagationNever
	// PropagationNotSupported executes non-transactionally, suspends the current transaction if one exists.
	PropagationNotSupported
	// PropagationRequiresNew creates a new transaction, suspends the current transaction if one exists.
	PropagationRequiresNew
	// PropagationSupports supports a current transaction, execute non-transactionally if none exists.
	PropagationSupports
)

type Settings

type Settings interface {
	// EnrichBy fills nil properties from external Settings.
	EnrichBy(external Settings) Settings

	// CtxKey returns trm.CtxKey for the trm.Transaction.
	CtxKey() CtxKey
	CtxKeyOrNil() *CtxKey
	SetCtxKey(*CtxKey) Settings

	// Propagation returns trm.Propagation.
	Propagation() Propagation
	PropagationOrNil() *Propagation
	SetPropagation(*Propagation) Settings

	// Cancelable defines that parent trm.Transaction can cancel child trm.Transaction or goroutines.
	Cancelable() bool
	CancelableOrNil() *bool
	SetCancelable(*bool) Settings

	// TimeoutOrNil returns time.Duration of the trm.Transaction.
	TimeoutOrNil() *time.Duration
	SetTimeout(*time.Duration) Settings
}

Settings is the configuration of the Manager. Preferable to implement as an immutable struct.

settings.Settings is a default implementation of Settings.

type TrFactory

type TrFactory func(ctx context.Context, s Settings) (context.Context, Transaction, error)

TrFactory is used in Manager to creates Transaction.

type Transaction

type Transaction interface {
	// Transaction returns the real transaction sql.Tx, sqlx.Tx or another.
	Transaction() interface{}
	// Commit the trm.Transaction.
	// Commit should be used only inside of Manager.
	Commit(context.Context) error
	// Rollback the trm.Transaction.
	// Rollback should be used only inside of Manager.
	Rollback(context.Context) error
	// IsActive returns true if the transaction started but not committed or rolled back.
	IsActive() bool
	// Closed returns a channel that's closed when transaction committed or rolled back.
	Closed() <-chan struct{}
}

Transaction wraps different transaction implementations.

type СtxManager

type СtxManager interface {
	// Default gets Transaction from context.Context by default CtxKey.
	Default(ctx context.Context) Transaction
	// SetDefault sets.Transaction in context.Context by default CtxKey.
	SetDefault(ctx context.Context, t Transaction) context.Context

	// ByKey gets Transaction from context.Context by CtxKey.
	ByKey(ctx context.Context, key CtxKey) Transaction
	// SetByKey sets Transaction in context.Context by.CtxKey.
	SetByKey(ctx context.Context, key CtxKey, t Transaction) context.Context
}

СtxManager sets and gets a Transaction in/from context.Context.