Clarify the effect of "early context terimination" and how to work around it

[zolstein]

The library docs on many functions state:

Contexts terminating too early negatively affect connection pooling and degrade the driver performance.

The warning of a potential foot-gun is good, but it's not entirely clear, and it suggests a lot of context that (as far as I can tell) isn't clearly documented anywhere:

• What does "too early" mean? Does it mean "any time before this function completes," or "before some critical step early in this function completes," or "any time before the entire result is consumed"?
• Exactly what effect does this have, individually, or if it happens repeatedly in a system?
• What are the best practices for preventing issues, especially given that the Go ecosystem relies heavily on context cancellation to control tasks? How should callers control the lifetime of queries?

The answers to these questions probably shouldn't be documented in every function, but they should probably be somewhere, and the documentation should probably point there.

Alternatively, could the performance degradation be fixed, so that this just isn't an issue anymore? Could the connection pooling be reworked to accommodate cancelled contexts? Or is that not possible for some reason?

[StephenCathcart]

Hey @zolstein, you're right that the current documentation could be clearer, and we agree this requires a more in-depth explanation in a centralised place rather than scattered across method docs. We’ll be working on that across the drivers team.

The Python async driver, which has a similar issue, offers some good guidance. Although it's Python-specific, the advice (don’t interrupt cleanup; don’t reuse cancelled sessions/transactions/results) applies to Go as well.

To try and clarify some of your questions:

What does “too early” mean?

In this context, “too early” generally means before the driver has had a chance to clean up and reset the connection. For example, if the context is cancelled before Result.Consume() or Session.Close() completes, the driver may not return the connection to the pool in a reusable state.

What’s the actual effect of early cancellation?

When a connection isn’t properly reset, it’s closed rather than reused. If this happens repeatedly (e.g. many short-lived or cancelled contexts), the connection pool can become exhausted, leading to degraded performance and increased connection churn.

Can this be avoided?

Ideally, let the driver cleanup methods (Close/Consume) finish before cancelling the context. That said, we recently improved the driver when closing connections; it now uses an internal context to avoid cleanup being interrupted by cancellation. You can see that change here.

Hope this helps somewhat!