bun.go

bun.go - Overview

1. Overview This file defines a wrapper BunDB around the bun.DB struct from the uptrace/bun library, providing transaction management and context-aware database access. It also includes functionality for adding query hooks.

2. Detailed Documentation

type transactorKey

type transactorKey struct{}

• Purpose: transactorKey is an empty struct used as a key for storing and retrieving transactions in a context.

type BunDB

type BunDB struct {
	*bun.DB
	settings factory.ScopedProviderSettings
}

• Purpose: BunDB is a wrapper around bun.DB that includes settings for logging and other configurations.
  • bun.DB: Embedded bun.DB instance for database operations.
  • settings: factory.ScopedProviderSettings for accessing logger and other settings.

func NewBunDB

func NewBunDB(settings factory.ScopedProviderSettings, sqldb *sql.DB, dialect schema.Dialect, hooks []SQLStoreHook, opts ...bun.DBOption) *BunDB {
	db := bun.NewDB(sqldb, dialect, opts...)

	for _, hook := range hooks {
		db.AddQueryHook(hook)
	}

	return &BunDB{db, settings}
}

• Purpose: NewBunDB creates a new BunDB instance.
  • Parameters:
    • settings: factory.ScopedProviderSettings - Settings for the database connection, including logger.
    • sqldb: *sql.DB - An existing sql.DB connection.
    • dialect: schema.Dialect - SQL dialect to use with bun.
    • hooks: []SQLStoreHook - A slice of SQLStoreHook to add to the bun.DB instance.
    • opts: ...bun.DBOption - Optional bun.DBOption for configuring the bun.DB instance.
  • Returns:
    • *BunDB: A pointer to the new BunDB instance.

func (*BunDB) RunInTxCtx

func (db *BunDB) RunInTxCtx(ctx context.Context, opts *sql.TxOptions, cb func(ctx context.Context) error) error {
	tx, ok := txFromContext(ctx)
	if ok {
		return cb(ctx)
	}

	// begin transaction
	tx, err := db.BeginTx(ctx, opts)
	if err != nil {
		return errors.Wrapf(err, errors.TypeInternal, errors.CodeInternal, "cannot begin transaction")
	}

	defer func() {
		if err := tx.Rollback(); err != nil {
			if err != sql.ErrTxDone {
				db.settings.Logger().ErrorContext(ctx, "cannot rollback transaction", "error", err)
			}
		}
	}()

	if err := cb(newContextWithTx(ctx, tx)); err != nil {
		return err
	}

	return tx.Commit()
}

• Purpose: RunInTxCtx executes a callback function cb within a database transaction. If a transaction already exists in the context, it reuses that transaction; otherwise, it starts a new transaction.
  • Parameters:
    • ctx: context.Context - The context for the transaction.
    • opts: *sql.TxOptions - Transaction options.
    • cb: func(ctx context.Context) error - The callback function to execute within the transaction.
  • Returns:
    • error: An error if the transaction fails to begin, commit, rollback, or if the callback function returns an error.

func (*BunDB) BunDBCtx

func (db *BunDB) BunDBCtx(ctx context.Context) bun.IDB {
	tx, ok := txFromContext(ctx)
	if !ok {
		return db.DB
	}
	return tx
}

• Purpose: BunDBCtx returns either the current transaction from the context, if one exists, or the underlying bun.DB instance.
  • Parameters:
    • ctx: context.Context - The context to check for a transaction.
  • Returns:
    • bun.IDB: The bun.Tx transaction if it exists in the context, otherwise the underlying bun.DB instance.

func newContextWithTx

func newContextWithTx(ctx context.Context, tx bun.Tx) context.Context {
	return context.WithValue(ctx, transactorKey{}, tx)
}

• Purpose: newContextWithTx creates a new context with the given transaction stored under the transactorKey.
  • Parameters:
    • ctx: context.Context - The original context.
    • tx: bun.Tx - The transaction to store in the new context.
  • Returns:
    • context.Context: A new context with the transaction stored.

func txFromContext

func txFromContext(ctx context.Context) (bun.Tx, bool) {
	tx, ok := ctx.Value(transactorKey{}).(bun.Tx)
	return tx, ok
}

• Purpose: txFromContext retrieves the transaction from the context, if it exists.
  • Parameters:
    • ctx: context.Context - The context to retrieve the transaction from.
  • Returns:
    • bun.Tx: The transaction, if it exists in the context.
    • bool: true if a transaction was found, false otherwise.

3. Code Examples N/A

4. Clarity and Accuracy The documentation is based on the code and aims to be precise.

5. Markdown & MDX Perfection Markdown syntax is correct.

6. Edge Cases To Avoid Breaking MDX All potential MDX breaking characters have been escaped.

7. Getting Started Relevance Include in Getting Started: NO