From b36b12b292d7cfc8330702fb27865e5ef04e6c9e Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 5 Dec 2017 22:12:52 -0500 Subject: [PATCH] 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 TryBot-Result: Gobot Gobot Reviewed-by: Daniel Theophanes --- src/database/sql/driver/driver.go | 27 +++++++++++++++++++-------- 1 file 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 -- 2.48.1