From: Daniel Theophanes <kardianos@gmail.com>
Date: Tue, 28 Apr 2020 14:31:12 +0000 (-0700)
Subject: database/sql: document Connect and Close may need a timeout
X-Git-Tag: go1.15beta1~323
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=ca854f3cdaa577930b385b61571d5176193b738e;p=gostls13.git

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 928b308d19..99fbd431be 100644
--- 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.