generic

Documentation

Overview

Package generic implements a generic Transacter which is compatible with a wide range of executors for different data sources.

Index

• type Executer
• type GormRemote
• type SQLRemote
• type SQLXRemote
• type Session
• type Transacter
  • func NewTransacter[Remote any, Resources any](executer Executer[Remote], ...) Transacter[Remote, Resources]
  • func (transacter Transacter[Remote, Resources]) Transact(ctx context.Context, run func(context.Context, Resources) error) (err error)
• type TransacterOption
  • func WithBackOffDelays[Remote any, Resources any](backoffs ...time.Duration) TransacterOption[Remote, Resources]
  • func WithBackOffRetry[Remote any, Resources any](retry func(backoffs []time.Duration, run func() error) error) TransacterOption[Remote, Resources]

Types

type Executer

type Executer[Remote any] interface {
	Execute(context.Context, func(Remote) error) error
}

Executer models the handler for the remote specific transaction logic. A call to execute should: - Open a new transaction - Run the provided function - On error roll back the transaction - On success commit the transaction The provided context is not passed down to the actual function that is executed, changes or additions to the context in Execute are not propagated.

type GormRemote

type GormRemote interface {
	AddError(err error) error
	Assign(attrs ...any) *gorm.DB
	Association(column string) *gorm.Association
	Attrs(attrs ...any) *gorm.DB
	AutoMigrate(dst ...any) error
	Clauses(conds ...clause.Expression) *gorm.DB
	// Connection is not guaranteed to be transaction safe when used with go-atomic
	Connection(fc func(tx *gorm.DB) error) (err error)
	Count(count *int64) *gorm.DB
	Create(value any) *gorm.DB
	CreateInBatches(value any, batchSize int) *gorm.DB
	// Stataements run on DB are not guaranteed to be transaction safe when used with go-atomic
	DB() (*sql.DB, error)
	Debug() *gorm.DB
	Delete(value any, conds ...any) *gorm.DB
	Distinct(args ...any) *gorm.DB
	Exec(rawSQL string, values ...any) *gorm.DB
	Find(dest any, conds ...any) *gorm.DB
	FindInBatches(dest any, batchSize int, fc func(tx *gorm.DB, batch int) error) *gorm.DB
	First(dest any, conds ...any) *gorm.DB
	FirstOrCreate(dest any, conds ...any) *gorm.DB
	FirstOrInit(dest any, conds ...any) *gorm.DB
	Get(key string) (any, bool)
	Group(name string) *gorm.DB
	Having(query any, args ...any) *gorm.DB
	InnerJoins(query string, args ...any) *gorm.DB
	InstanceGet(key string) (any, bool)
	InstanceSet(key string, value any) *gorm.DB
	Joins(query string, args ...any) *gorm.DB
	Last(dest any, conds ...any) *gorm.DB
	Limit(limit int) *gorm.DB
	Migrator() gorm.Migrator
	Model(value any) *gorm.DB
	Not(query any, args ...any) *gorm.DB
	Offset(offset int) *gorm.DB
	Omit(columns ...string) *gorm.DB
	Or(query any, args ...any) *gorm.DB
	Order(value any) *gorm.DB
	Pluck(column string, dest any) *gorm.DB
	Preload(query string, args ...any) *gorm.DB
	Raw(rawSQL string, values ...any) *gorm.DB
	RollbackTo(name string) *gorm.DB
	Row() *sql.Row
	Rows() (*sql.Rows, error)
	Save(value any) *gorm.DB
	SavePoint(name string) *gorm.DB
	Scan(dest any) *gorm.DB
	ScanRows(rows *sql.Rows, dest any) error
	Scopes(funcs ...func(*gorm.DB) *gorm.DB) *gorm.DB
	Select(query any, args ...any) *gorm.DB
	Session(config *gorm.Session) *gorm.DB
	Set(key string, value any) *gorm.DB
	SetupJoinTable(model any, field string, joinTable any) error
	Table(name string, args ...any) *gorm.DB
	Take(dest any, conds ...any) *gorm.DB
	ToSQL(queryFn func(tx *gorm.DB) *gorm.DB) string
	Unscoped() *gorm.DB
	Update(column string, value any) *gorm.DB
	UpdateColumn(column string, value any) *gorm.DB
	UpdateColumns(values any) *gorm.DB
	Updates(values any) *gorm.DB
	Use(plugin gorm.Plugin) error
	Where(query any, args ...any) *gorm.DB
	WithContext(ctx context.Context) *gorm.DB
}

GormRemote is a subset of the methods on gorm.io/gorm.DB, explicitly excluding Transaction related methods to possibly avoid programming errors through manually using transactions within Transacter.Transact closures.

type SQLRemote

type SQLRemote interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

SQLRemote is a subset of the shared methods of sql.DB and sql.Tx To push context based development purposefully only the Context variants are used.

type SQLXRemote

type SQLXRemote interface {
	BindNamed(query string, arg any) (string, []any, error)
	DriverName() string
	GetContext(ctx context.Context, dest any, query string, args ...any) error
	MustExecContext(ctx context.Context, query string, args ...any) sql.Result
	NamedExecContext(ctx context.Context, query string, arg any) (sql.Result, error)
	NamedQuery(query string, arg any) (*sqlx.Rows, error)
	NamedStmtContext(ctx context.Context, stmt *sqlx.NamedStmt) *sqlx.NamedStmt
	PrepareNamedContext(ctx context.Context, query string) (*sqlx.NamedStmt, error)
	PreparexContext(ctx context.Context, query string) (*sqlx.Stmt, error)
	QueryRowxContext(ctx context.Context, query string, args ...any) *sqlx.Row
	QueryxContext(ctx context.Context, query string, args ...any) (*sqlx.Rows, error)
	Rebind(query string) string
	SelectContext(ctx context.Context, dest any, query string, args ...any) error
}

SQLXRemote is a subset of the shared methods of sqlx.DB and sqlx.Tx To push context based development purposefully only the Context variants are used. The exception to this rule is NamedQuery, as the sqlx project apparently refuses to include a contextualized version on sqlx.Tx (see: https://github.com/jmoiron/sqlx/issues/447)

type Session

type Session[Remote any] struct {
	Tx Remote
}

Session models all info passed from transacter through context to other nested Transact calls.

type Transacter

type Transacter[Remote any, Resources any] struct {
	// contains filtered or unexported fields
}

Transacter implements the Transacter interface for sqlx compatible databases. It flattens statements on nested uses of the Transact method into one sqlx transaction.

func NewTransacter

func NewTransacter[Remote any, Resources any](
	executer Executer[Remote],
	createResources func(
		ctx context.Context,
		transacter *Transacter[Remote, Resources],
		tx Remote,
	) (Resources, error),
	opts ...TransacterOption[Remote, Resources],
) Transacter[Remote, Resources]

NewTransacter creates a new Transacter. Remote is the type passed to the createResources function, ie a sql.DB or sql.Tx object (depending on the chosen executor). The executor must match the chosen remote type. It is useful to use an interface as remote like the SQLRemote or SQLXRemote interfaces, as it permits the use of eg repositories with both sql.DB and sql.Tx.

By default sets:

• atomic.DefaultRetry as the retry function.
• atomic.DefaultBackoffs as the backoffs to use on retry.

createResources is supposed to do any setup or new instantiation of members of Resources, ie create new repositories using the provided Remote. For an example view see [example.Example].

func (Transacter[Remote, Resources]) Transact

func (transacter Transacter[Remote, Resources]) Transact(
	ctx context.Context,
	run func(context.Context, Resources) error,
) (err error)

Transact will run run in a sqlx Session. If a session is present in ctx at atomic.SessionContextKey it will use the existing session, else it will create a new session and insert it into the context. It does not support nested transactions, rather all statements are flattened into a single transaction. Using the Session it executes the resource creation function which is provided on creation of the transacter to produce the resources for calling run. If an error is returned from run the outermost call of Transact will handle the error with the provided retry function.

type TransacterOption

type TransacterOption[Remote any, Resources any] func(*Transacter[Remote, Resources])

TransacterOption is used to configure a Transacter.

func WithBackOffDelays

func WithBackOffDelays[Remote any, Resources any](
	backoffs ...time.Duration,
) TransacterOption[Remote, Resources]

WithBackOffDelays sets the backoffs to use on retry. The maximum amount of retries is determined by the length of backoffs.

func WithBackOffRetry

func WithBackOffRetry[Remote any, Resources any](
	retry func(backoffs []time.Duration, run func() error) error,
) TransacterOption[Remote, Resources]

WithBackOffRetry sets the retry function which manages automatic retries on errors.