Why not just use the context.Context created in HandleCancel? (e.g. shutdownCtx)

I think you're suggesting something like this:

type CancelAndDrainContextWatcherHandler struct {
	Conn          *PgConn
	DeadlineDelay time.Duration
	DrainTimeout  time.Duration

	doneFn context.CancelFunc   // replaces cancelFinishedChan
	doneCtx context.Context     // replaces cancelFinishedChan
	stopFn context.CancelFunc
}

func (h *CancelAndDrainContextWatcherHandler) HandleCancel(_ context.Context) {
	h.doneCtx, h.doneFn = context.WithCancel(context.Background())
	cancelCtx, stop := context.WithCancel(context.Background())
	h.stopFn = stop

	deadline := time.Now().Add(h.deadlineDelay())
	h.Conn.conn.SetDeadline(deadline)

	go func() {
		defer h.doneFn()
		reqCtx, cancel := context.WithDeadline(cancelCtx, deadline)
		defer cancel()
		h.Conn.CancelRequest(reqCtx)
	}()
}

func (h *CancelAndDrainContextWatcherHandler) HandleUnwatchAfterCancel() {
	if h.stopFn != nil {
		h.stopFn()
	}
	if h.doneCtx != nil {
		<-h.doneCtx.Done()
	}
	// ... rest unchanged
}

this would work fine but is more allocation and diverges from the pattern in the other handler...I don't personally see much reason to prefer it, but I'm not against making that change.

Similar to what I said below, this should all be handled in pgxpool or puddle (somehow), and not done at the PgConn layer.

this is how I would do it if I owned this library, but I'm matching the existing style - there are no duration constants anywhere else.

why is HandleCancel()'s arg being ignored and not passed to context.WithCancel()? Is this a different lifetime scope? It looks like we intend to inherit from the passed in context.

the ctx passed here is already cancelled, this is the same pattern used by the existing handler:

Can this be replaced with a errgroup.Group?

this pattern matches the pre-existing handler, there's only 1 goroutine here, and no meaningful error to return

This can block indefinitely

look at https://github.com/jackc/pgx/pull/2534/changes#diff-361e75a80ec6958cfb843b7e092b63e5bbf6c6b3a20734e1a43f1f722a35c063R57-R58:

defer close(doneCh) // doneCh here is h.cancelFinishedChan
reqCtx, cancel := context.WithDeadline(cancelCtx, deadline) // cancelCtx is cancelled by stopFn

so if stopFn gets called, this channel is closed, and if that doesn't happen for some reason, it's still closed by the deadline