database/sql: document Connect and Close may need a timeout

Opening a connection with Connect should still create a derived
context with a timeout because some clients will not use a timeout
and the connection pool may open a connection asynchronously.

Likewise, if a connection close makes a network operation it should
provide some type of sane timeout for the operation.

Fixes #38185

Change-Id: I9b7ce2996c81c486170dcc84b12672a99610fa27
Reviewed-on: https://go-review.googlesource.com/c/go/+/230438
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>

diff --git a/src/database/sql/driver/driver.go b/src/database/sql/driver/driver.go
index 928b308d1946c7072132dcea65a739292fce4444..99fbd431be7867f07457a9b35ec0a765d0966685 100644 (file)
--- a/src/database/sql/driver/driver.go
+++ b/src/database/sql/driver/driver.go
@@ -123,7 +123,9 @@ type Connector interface {
        //
        // The provided context.Context is for dialing purposes only
        // (see net.DialContext) and should not be stored or used for
-       // other purposes.
+       // other purposes. A default timeout should still be used
+       // when dialing as a connection pool may call Connect
+       // asynchronously to any query.
        //
        // The returned connection is only used by one goroutine at a
        // time.
@@ -234,6 +236,9 @@ type Conn interface {
        // connections and only calls Close when there's a surplus of
        // idle connections, it shouldn't be necessary for drivers to
        // do their own connection caching.
+       //
+       // Drivers must ensure all network calls made by Close
+       // do not block indefinitely (e.g. apply a timeout).
        Close() error
 
        // Begin starts and returns a new transaction.
@@ -320,6 +325,9 @@ type Stmt interface {
        //
        // As of Go 1.1, a Stmt will not be closed if it's in use
        // by any queries.
+       //
+       // Drivers must ensure all network calls made by Close
+       // do not block indefinitely (e.g. apply a timeout).
        Close() error
 
        // NumInput returns the number of placeholder parameters.