Transactions hang indefinitely when number of concurrent calls equal MaxConns value

[Seokky]

When executing exactly N concurrent transactions (where N = MaxConns of the pgxpool.Pool), all transactions hang indefinitely and never complete. The issue disappears when reducing the number of concurrent calls to N − 1.

Create a pool with default MaxConns = 10:

func New(dburl string) (*pgxpool.Pool, error) {
    dbpool, err := pgxpool.New(context.Background(), dburl)
    if err != nil {
        return nil, fmt.Errorf("failed to connect db: %w", err)
    }
    return dbpool, nil
}

Define a repository method that:

• Starts a transaction (Begin),
• Executes a simple query (SELECT COUNT(*) FROM users),
• Commits or rolls back the transaction.

type Repository struct {
    pgclient *pgxpool.Pool
}

func (repo *Repository) Test(i int) (err error) {
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()

    tx, beginErr := repo.pgclient.Begin(ctx)
    if beginErr != nil {
        return beginErr
    }

    defer func() {
        if err != nil {
            rollbackErr := tx.Rollback(ctx)
            if rollbackErr != nil {
                err = rollbackErr
            }
            return
        }
        commitErr := tx.Commit(ctx)
        if commitErr != nil {
            err = commitErr
        }
    }()

    var c int
    err = repo.pgclient.QueryRow(ctx, "SELECT COUNT(*) FROM achievements").Scan(&c)
    if err != nil {
        fmt.Println(i, err)
        return err
    }

    return err
}

Execute exactly MaxConns concurrent calls:

for i := 0; i < 10; i++ { // MaxConns = 10
    go repository.Test(i)
}

Expected behavior
Transactions are released one by one.

Actual behavior
All 10 transactions hang indefinitely.

Version

• Go: 1.25.3
• PostgreSQL: PostgreSQL 18.0 on aarch64-unknown-linux-musl, compiled by gcc (Alpine 14.2.0) 14.2.0, 64-bit
• pgx: v5.7.6

Additional context
The issue disappears when reducing the number of concurrent calls to N − 1.

[Seokky]

Semaphore is solution for me:

var txSemaphore chan struct{}

func New(dburl string) (*pgxpool.Pool, error) {
	dbpool, err := pgxpool.New(context.Background(), dburl)
	if err != nil {
        	return nil, fmt.Errorf("failed to connect db: %w", err)
	}

	txSemaphore = make(chan struct{}, dbpool.Stat().MaxConns()/2)

	return dbpool, nil
}

func BeginTx(ctx context.Context, pgclient *pgxpool.Pool) (pgx.Tx, error) {
	txSemaphore <- struct{}{}        
	defer func() { <-txSemaphore }()

	return pgclient.Begin(ctx)
}

But shouldn't the library by default implement protection for such cases?

[jackc]

err = repo.pgclient.QueryRow(ctx, "SELECT COUNT(*) FROM achievements").Scan(&c)

This will acquire a new connection, not use the tx.

Do this instead:

err = tx.QueryRow(ctx, "SELECT COUNT(*) FROM achievements").Scan(&c)

[Seokky]

Yes, of course. But this is a test code specifically for reproducing the problem. And the problem, as I wrote, is that all transactions hang when the maximum number of connections is reached.

[jackc]

Yes, of course. But this is a test code specifically for reproducing the problem. And the problem, as I wrote, is that all transactions hang when the maximum number of connections is reached.

That's exactly what I would expect to happen given the bug above. Please see if you can make a repro case with that fixed ... pgxpool has been in production many places for years, so I would be very surprised if the deadlock you are encountering occurs without a bug in the calling code.