ql

Documentation

Index

• Variables
• func Exec(ctx TxContext, stmt string, args ...any) error
• func ExecAffected(ctx TxContext, stmt string, args ...any) (int, error)
• func ExecNamed(ctx TxContext, stmt string, args any) error
• func ExecNamedAffected(ctx TxContext, stmt string, args any) (int, error)
• func FirstOrNil[T any](ctx TxContext, query string, args ...any) (*T, error)
• func Get[T any](ctx TxContext, query string, args ...interface{}) (*T, error)
• func InAnyTransaction(ctx context.Context, db TxStarter, fun func(ctx TxContext) error) error
• func InAnyTransactionWithResult[R any](ctx context.Context, db TxStarter, fun func(ctx TxContext) (R, error)) (R, error)
• func InExistingTransaction(ctx context.Context, fun func(ctx TxContext) error) error
• func InExistingTransactionWithResult[R any](ctx context.Context, fun func(ctx TxContext) (R, error)) (R, error)
• func InNewTransaction(ctx context.Context, db TxStarter, fun func(ctx TxContext) error) error
• func InNewTransactionWithResult[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 ...any) ([]T, error)
• type Action
• type Hooks
• type QueryIter
  • func Iter[T any](ctx TxContext, query string, args ...any) (*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 StringArray
  • func NewStringArray(value []string) StringArray
  • func (s *StringArray) Scan(src any) error
• type Tx
• type TxContext
  • func WithCancel(parent TxContext) (TxContext, context.CancelFunc)
  • func WithDeadline(parent TxContext, deadline time.Time) (TxContext, context.CancelFunc)
  • func WithTimeout(parent TxContext, timeout time.Duration) (TxContext, context.CancelFunc)
  • func WithValue(parent TxContext, key any, value any) TxContext
• type TxStarter

Variables

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

Functions

func Exec

func Exec(ctx TxContext, stmt string, args ...any) error

Exec just execute the given statement in the provided transaction.

func ExecAffected

func ExecAffected(ctx TxContext, stmt string, args ...any) (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 ExecNamed

func ExecNamed(ctx TxContext, stmt string, args any) error

ExecNamed just execute the given statement in the provided transaction.

func ExecNamedAffected

func ExecNamedAffected(ctx TxContext, stmt string, args any) (int, error)

ExecNamedAffected executes the given statement and returns the number of rows that were affected by the statement.

func FirstOrNil

func FirstOrNil[T any](ctx TxContext, query string, args ...any) (*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(ctx context.Context, db TxStarter, fun func(ctx TxContext) error) error

InAnyTransaction calls InAnyTransactionWithResult without returning a result.

func InAnyTransactionWithResult

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

InAnyTransactionWithResult checks the context for an existing transaction created by InNewTransactionWithResult. 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 InNewTransactionWithResult regarding error handling.

func InExistingTransaction

func InExistingTransaction(ctx context.Context, fun func(ctx TxContext) error) error

InExistingTransaction calls InExistingTransactionWithResult without returning the error.

func InExistingTransactionWithResult

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

InExistingTransactionWithResult 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 InNewTransactionWithResult.

This function will not rollback the transaction on error.

func InNewTransaction

func InNewTransaction(ctx context.Context, db TxStarter, fun func(ctx TxContext) error) error

InNewTransaction calls InNewTransactionWithResult without returning a result

func InNewTransactionWithResult

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

InNewTransactionWithResult 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 ...any) ([]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 ...any) (*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 StringArray

type StringArray []string

func NewStringArray

func NewStringArray(value []string) StringArray

func (*StringArray) Scan

func (s *StringArray) Scan(src any) error

type Tx

type Tx interface {
	sqlx.ExtContext
}

Tx describes a simple transaction

type TxContext

type TxContext interface {
	context.Context
	Tx
	Hooks
	sqlx.PreparerContext

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

	// CommitAndChain performs a commit, runs all OnCommit hooks and creates a new transaction
	// using the postgres `COMMIT AND CHAIN` command.
	CommitAndChain() error
}

func WithCancel

func WithCancel(parent TxContext) (TxContext, context.CancelFunc)

WithCancel is a wrapper around context.WithCancel

func WithDeadline

func WithDeadline(parent TxContext, deadline time.Time) (TxContext, context.CancelFunc)

WithDeadline is a wrapper around context.WithDeadline

func WithTimeout

func WithTimeout(parent TxContext, timeout time.Duration) (TxContext, context.CancelFunc)

WithTimeout is a wrapper around context.WithTimeout

func WithValue

func WithValue(parent TxContext, key any, value any) TxContext

WithValue is a wrapper around context.WithValue

type TxStarter

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