database/sql/driver: explain Driver vs DriverContext vs Connector

The docs make it seem like they are all things a single object
would implement. That's true of Driver and DriverContext,
but Connector is really something else. Attempt to clarify.

Change-Id: I8fdf1cff855a0fbe37ea22720c082045c719a267
Reviewed-on: https://go-review.googlesource.com/82082
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Daniel Theophanes <kardianos@gmail.com>

1 files changed, 19 insertions, 8 deletions

diff --git a/src/database/sql/driver/driver.go b/src/database/sql/driver/driver.go
index b9bf19c04d..83b2b3f535 100644
--- a/src/database/sql/driver/driver.go
+++ b/src/database/sql/driver/driver.go
@@ -42,6 +42,10 @@ type NamedValue struct {
 
 // Driver is the interface that must be implemented by a database
 // driver.
+//
+// Database drivers may implement DriverContext for access
+// to contexts and to parse the name only once for a pool of connections,
+// instead of once per connection.
 type Driver interface {
 	// Open returns a new connection to the database.
 	// The name is a string in a driver-specific format.
@@ -55,20 +59,27 @@ type Driver interface {
 	Open(name string) (Conn, error)
 }
 
-// DriverContext enhances the Driver interface by returning a Connector
-// rather then a single Conn.
-// It separates out the name parsing step from actually connecting to the
-// database. It also gives dialers access to the context by using the
-// Connector.
+// If a Driver implements DriverContext, then sql.DB will call
+// OpenConnector to obtain a Connector and then invoke
+// that Connector's Conn method to obtain each needed connection,
+// instead of invoking the Driver's Open method for each connection.
+// The two-step sequence allows drivers to parse the name just once
+// and also provides access to per-Conn contexts.
 type DriverContext interface {
 	// OpenConnector must parse the name in the same format that Driver.Open
 	// parses the name parameter.
 	OpenConnector(name string) (Connector, error)
 }
 
-// Connector is an optional interface that drivers can implement.
-// It allows drivers to provide more flexible methods to open
-// database connections without requiring the use of a DSN string.
+// A Connector represents a driver in a fixed configuration
+// and can create any number of equivalent Conns for use
+// by multiple goroutines.
+//
+// A Connector can be passed to sql.OpenDB, to allow drivers
+// to implement their own sql.DB constructors, or returned by
+// DriverContext's OpenConnector method, to allow drivers
+// access to context and to avoid repeated parsing of driver
+// configuration.
 type Connector interface {
 	// Connect returns a connection to the database.
 	// Connect may return a cached connection (one previously