sqlxtransaction

Documentation

Overview

Package sqlxtransaction solves a common reliability problem in Go database code: correctly handling begin/commit/rollback control flow around business logic executed inside a sqlx transaction.

Problem

Manual transaction handling is repetitive and easy to get wrong. Typical bugs include forgetting rollback on error paths, attempting double rollback, committing after a failed operation, or returning partial error context. These issues can silently leak inconsistent state and make production incidents harder to debug.

This package provides a small execution wrapper that centralizes the transaction lifecycle and enforces a safe default pattern.

How It Works

Exec and ExecWithOptions accept a caller-provided ExecFunc and run it inside a sqlx transaction:

1. Start a transaction with DB.BeginTxx.
2. Execute the provided function with the transaction object.
3. Commit if execution succeeds.
4. Roll back automatically if execution fails or commit is not reached.

Rollback behavior is deferred and guarded:

• rollback is skipped after a successful commit,
• `sql.ErrTxDone` is ignored during deferred rollback,
• rollback failures are joined with the current error so diagnostics are not lost.

Key Features

• Minimal API: call Exec for default transaction options, or ExecWithOptions for custom sql.TxOptions (isolation level, read-only, etc.).
• Testability by interface: the DB interface abstracts `BeginTxx`, making the transaction entrypoint easy to mock.
• Strong error context: begin, run, commit, and rollback failures are wrapped with actionable messages.
• Safe-by-default lifecycle: commit happens only on successful function completion; otherwise rollback is guaranteed.

Usage

err := sqlxtransaction.Exec(ctx, db, func(ctx context.Context, tx *sqlx.Tx) error {
    // Execute all related SQL operations using tx.
    // Return an error to trigger rollback.
    return nil
})
if err != nil {
    return err
}

For a similar helper based on the standard database/sql package (instead of github.com/jmoiron/sqlx), see: github.com/tecnickcom/nurago/pkg/sqltransaction

Index

• Variables
• func Exec(ctx context.Context, db DB, run ExecFunc) error
• func ExecWithOptions(ctx context.Context, db DB, run ExecFunc, opts *sql.TxOptions) (err error)
• type DB
• type ExecFunc

Variables

var (
	// ErrNilDB is returned when the provided DB is nil.
	ErrNilDB = errors.New("db must not be nil")

	// ErrNilExecFunc is returned when the provided ExecFunc is nil.
	ErrNilExecFunc = errors.New("exec function must not be nil")
)

Functions

func Exec

func Exec(ctx context.Context, db DB, run ExecFunc) error

Exec executes function inside sqlx transaction with automatic rollback on error and guarded cleanup.

func ExecWithOptions

func ExecWithOptions(ctx context.Context, db DB, run ExecFunc, opts *sql.TxOptions) (err error)

ExecWithOptions executes function in sqlx transaction with custom isolation level or read-only option; returns joined errors if commit/rollback both fail.

Types

type DB

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

DB defines the transaction entry point required by Exec and ExecWithOptions.

type ExecFunc

type ExecFunc func(ctx context.Context, tx *sqlx.Tx) error

ExecFunc is the type of the function to be executed inside a SQL Transaction.