Add additional flavor in leadership when transaction fails to start

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
 }