Add additional flavor in leadership when transaction fails to start

Related to #1077, a common problem that users run into is that there
database pool is configured to be too small, and a common place they run
into this is as a River client is trying to elect itself.

Here, add a little bit of custom flavor to a deadline exceeded error
that occurs during leadership election. This is certainly not an
exhaustive way to reveal these errors (it only goes in one spot), but
the idea is that we put it in a common error spot, and it should improve
things incrementally.

Author: brandur

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Basic stuck detection after a job's exceeded its timeout and still not returned after the executor's initiated context cancellation and waited a short margin for the cancellation to take effect. [PR #1097](https://github.com/riverqueue/river/pull/1097).
+- Add a little more error flavor for when encountering a deadline exceeded error on leadership election suggesting that the user may want to try increasing their database pool size. [PR #1101](https://github.com/riverqueue/river/pull/1101).
 
 ## [0.29.0-rc.1] - 2025-12-04
 

internal/leadership/elector.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log/slog"
 	"strings"
 	"sync"
@@ -567,27 +568,38 @@ func attemptElectOrReelect(ctx context.Context, exec riverdriver.Executor, alrea
 	ctx, cancel := context.WithTimeout(ctx, deadlineTimeout)
 	defer cancel()
 
-	return dbutil.WithTxV(ctx, exec, func(ctx context.Context, exec riverdriver.ExecutorTx) (bool, error) {
-		if _, err := exec.LeaderDeleteExpired(ctx, &riverdriver.LeaderDeleteExpiredParams{
-			Now:    params.Now,
-			Schema: params.Schema,
-		}); err != nil {
-			return false, err
+	execTx, err := exec.Begin(ctx)
+	if err != nil {
+		var additionalDetail string
+		if errors.Is(err, context.DeadlineExceeded) {
+			additionalDetail = " (a common cause of this is a database pool that's at its connection limit; you may need to increase maximum connections)"
 		}
 
-		var (
-			elected bool
-			err     error
-		)
-		if alreadyElected {
-			elected, err = exec.LeaderAttemptReelect(ctx, params)
-		} else {
-			elected, err = exec.LeaderAttemptElect(ctx, params)
-		}
-		if err != nil {
-			return false, err
-		}
+		return false, fmt.Errorf("error beginning transaction: %w%s", err, additionalDetail)
+	}
+	defer dbutil.RollbackWithoutCancel(ctx, execTx)
 
-		return elected, nil
-	})
+	if _, err := execTx.LeaderDeleteExpired(ctx, &riverdriver.LeaderDeleteExpiredParams{
+		Now:    params.Now,
+		Schema: params.Schema,
+	}); err != nil {
+		return false, err
+	}
+
+	var elected bool
+	if alreadyElected {
+		elected, err = execTx.LeaderAttemptReelect(ctx, params)
+
+	} else {
+		elected, err = execTx.LeaderAttemptElect(ctx, params)
+	}
+	if err != nil {
+		return false, err
+	}
+
+	if err := execTx.Commit(ctx); err != nil {
+		return false, fmt.Errorf("error committing transaction: %w", err)
+	}
+
+	return elected, nil
 }