ql

Documentation

Index

• Variables
• func Exec(ctx TxContext, stmt string, args ...interface{}) error
• func ExecAffected(ctx TxContext, stmt string, args ...interface{}) (int, error)
• func FirstOrNil[T any](ctx TxContext, query string, args ...interface{}) (*T, error)
• func Get[T any](ctx TxContext, query string, args ...interface{}) (*T, error)
• func InAnyTransaction[R any](ctx context.Context, db TxStarter, fun func(ctx TxContext) (R, error)) (R, error)
• func InExistingTransaction[R any](ctx context.Context, fun func(ctx TxContext) (R, error)) (R, error)
• func InNewTransaction[R any](ctx context.Context, db TxStarter, fun func(ctx TxContext) (R, error)) (R, error)
• func NoRollback(err error) error
• func Select[T any](ctx TxContext, query string, args ...interface{}) ([]T, error)
• type Action
• type Hooks
• type QueryIter
  • func Iter[T any](ctx TxContext, query string, args ...interface{}) (*QueryIter[T], error)
  • func (q *QueryIter[T]) Close() error
  • func (q *QueryIter[T]) ForEach(consumer func(row T) error) error
  • func (q *QueryIter[T]) HasNext() bool
  • func (q *QueryIter[T]) Next() (T, error)
• type Tx
• type TxContext
• type TxStarter

Variables

var ErrNoTransaction = errors.New("no transaction in context")

var ErrTransactionExistInContext = errors.New("transaction exists in context")

Functions

func Exec

func Exec(ctx TxContext, stmt string, args ...interface{}) error

Exec just execute the given statement in the provided transaction.

func ExecAffected

func ExecAffected(ctx TxContext, stmt string, args ...interface{}) (int, error)

ExecAffected executes the given statement and returns the number of rows that were affected by the statement. This is especially useful with an `UPDATE` statement.

func FirstOrNil

func FirstOrNil[T any](ctx TxContext, query string, args ...interface{}) (*T, error)

FirstOrNil is similar to Get. It will only scan the first row of the result. If the query does not return any row, this method returns a value of nil and no error.

func Get

func Get[T any](ctx TxContext, query string, args ...interface{}) (*T, error)

Get runs the given query and parses the result into an object of type T. If not object can be found the method will return sql.ErrNoRows and a value of nil.

func InAnyTransaction

func InAnyTransaction[R any](ctx context.Context, db TxStarter, fun func(ctx TxContext) (R, error)) (R, error)

InAnyTransaction checks the context for an existing transaction created by InNewTransaction. If a transaction exists it will run the given operation in the transaction context. If no transaction exists, a new transaction will be created.

See InNewTransaction regarding error handling.

func InExistingTransaction

func InExistingTransaction[R any](ctx context.Context, fun func(ctx TxContext) (R, error)) (R, error)

InExistingTransaction runs the given operation in the transaction that is hidden in the provided Context instance. If the context does not contain any transaction, ErrNoTransaction will be returned. The context must contain a transaction created by InNewTransaction.

This function will not rollback the transaction on error.

func InNewTransaction

func InNewTransaction[R any](ctx context.Context, db TxStarter, fun func(ctx TxContext) (R, error)) (R, error)

InNewTransaction creates a new transaction and executes the given function within that transaction. The method will automatically roll back the transaction if an error is returned or otherwise commit it. This excludes the 'ErrNoRows' error. This error never triggers a rollback.

This behaviour can be overwritten by wrapping the error into NoRollback. The transaction will be committed in spite of the error present.

The caller can also trigger a rollback with no error present by simply calling Rollback on the transaction.

If the context already contains a transaction then ErrTransactionExistInContext will be returned as error and the actual operation will not be executed.

func NoRollback

func NoRollback(err error) error

func Select

func Select[T any](ctx TxContext, query string, args ...interface{}) ([]T, error)

Select scans the result into a slice of element type T using sqlx.SelectContext.

Types

type Action

type Action func()

An Action can be schedule to run after a commit or after a rollback of a transaction to execute some (infallible) side effects.

type Hooks

type Hooks interface {
	// OnCommit schedules some side effect that is only run if the transaction
	// commits successfully. The Action is run after the transaction is committed and must
	// not access the database again.
	OnCommit(action Action)
}

type QueryIter

type QueryIter[T any] struct {
	// contains filtered or unexported fields
}

func Iter

func Iter[T any](ctx TxContext, query string, args ...interface{}) (*QueryIter[T], error)

Iter returns a typed iterator over the rows of the given query. It is the callers responsibility to close the returned iterator. Most of the time, you want to use Select. Only use this, if you are expecting millions of rows.

func (*QueryIter[T]) Close

func (q *QueryIter[T]) Close() error

func (*QueryIter[T]) ForEach

func (q *QueryIter[T]) ForEach(consumer func(row T) error) error

func (*QueryIter[T]) HasNext

func (q *QueryIter[T]) HasNext() bool

func (*QueryIter[T]) Next

func (q *QueryIter[T]) Next() (T, error)

type Tx

type Tx interface {
	sqlx.ExecerContext
	sqlx.QueryerContext
}

Tx describes a simple transaction

type TxContext

type TxContext interface {
	context.Context
	Tx
	Hooks

	// WithContext returns a new TxContext with the given "real" context.
	WithContext(ctx context.Context) TxContext
}

type TxStarter

type TxStarter interface {
	BeginTxx(ctx context.Context, opts *sql.TxOptions) (*sqlx.Tx, error)
}