Warn of the impact of early context terminations

Since 78c1c75, an early context
termination results in the active connection's socket to be closed.

This potentially valid connection will be marked as dead and will
not be a candidate for future reuse.

Moreover, the cleanup of idle connections that are too old may not
even occur if the context has terminated. This results in the pool
gradually filling up with potentially bad connections.

Author: fbiville

neo4j/driver_with_context.go

@@ -72,6 +72,7 @@ type DriverWithContext interface {
 	// VerifyConnectivity checks that the driver can connect to a remote server or cluster by
 	// establishing a network connection with the remote. Returns nil if successful
 	// or error describing the problem.
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	VerifyConnectivity(ctx context.Context) error
 	// Close the driver and all underlying connections
 	Close(ctx context.Context) error
@@ -81,6 +82,7 @@ type DriverWithContext interface {
 	IsEncrypted() bool
 	// GetServerInfo attempts to obtain server information from the target Neo4j
 	// deployment
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	GetServerInfo(ctx context.Context) (ServerInfo, error)
 }
 
@@ -440,6 +442,8 @@ func (d *driverWithContext) Close(ctx context.Context) error {
 // functions.
 // Since ResultTransformer implementations are inherently stateful, the function must return a new ResultTransformer
 // instance every time it is called.
+//
+// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 func ExecuteQuery[T any](
 	ctx context.Context,
 	driver DriverWithContext,

neo4j/session_with_context.go

@@ -54,16 +54,21 @@ type SessionWithContext interface {
 	LastBookmarks() Bookmarks
 	lastBookmark() string
 	// BeginTransaction starts a new explicit transaction on this session
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	BeginTransaction(ctx context.Context, configurers ...func(*TransactionConfig)) (ExplicitTransaction, error)
 	// ExecuteRead executes the given unit of work in a AccessModeRead transaction with
 	// retry logic in place
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	ExecuteRead(ctx context.Context, work ManagedTransactionWork, configurers ...func(*TransactionConfig)) (any, error)
 	// ExecuteWrite executes the given unit of work in a AccessModeWrite transaction with
 	// retry logic in place
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	ExecuteWrite(ctx context.Context, work ManagedTransactionWork, configurers ...func(*TransactionConfig)) (any, error)
 	// Run executes an auto-commit statement and returns a result
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Run(ctx context.Context, cypher string, params map[string]any, configurers ...func(*TransactionConfig)) (ResultWithContext, error)
 	// Close closes any open resources and marks this session as unusable
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Close(ctx context.Context) error
 
 	legacy() Session

neo4j/transaction_with_context.go

@@ -35,13 +35,17 @@ type ManagedTransaction interface {
 // ExplicitTransaction represents a transaction in the Neo4j database
 type ExplicitTransaction interface {
 	// Run executes a statement on this transaction and returns a result
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Run(ctx context.Context, cypher string, params map[string]any) (ResultWithContext, error)
 	// Commit commits the transaction
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Commit(ctx context.Context) error
 	// Rollback rolls back the transaction
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Rollback(ctx context.Context) error
 	// Close rolls back the actual transaction if it's not already committed/rolled back
 	// and closes all resources associated with this transaction
+	// Contexts terminating too early negatively affect connection pooling and degrade the driver performance.
 	Close(ctx context.Context) error
 
 	// legacy returns the non-cancelling, legacy variant of this ExplicitTransaction type