database/sql: document non-open of Open; add Ping

Fixes #4804

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/7819043

diff --git a/src/pkg/database/sql/sql.go b/src/pkg/database/sql/sql.go
index 6d52d2986d1821a49a0ce6218a8c8f7939a2de46..d351fbc243d846334acaa758b092fbfc60396bcb 100644 (file)
--- a/src/pkg/database/sql/sql.go
+++ b/src/pkg/database/sql/sql.go
@@ -258,13 +258,15 @@ func (db *DB) removeDep(x finalCloser, dep interface{}) error {
 //
 // Most users will open a database via a driver-specific connection
 // helper function that returns a *DB.
+//
+// Open may just validate its arguments without creating a connection
+// to the database. To verify that the data source name is valid, call
+// Ping.
 func Open(driverName, dataSourceName string) (*DB, error) {
        driveri, ok := drivers[driverName]
        if !ok {
                return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName)
        }
-       // TODO: optionally proactively connect to a Conn to check
-       // the dataSourceName: golang.org/issue/4804
        db := &DB{
                driver:    driveri,
                dsn:       dataSourceName,
@@ -275,6 +277,20 @@ func Open(driverName, dataSourceName string) (*DB, error) {
        return db, nil
 }
 
+// Ping verifies a connection to the database is still alive,
+// establishing a connection if necessary.
+func (db *DB) Ping() error {
+       // TODO(bradfitz): give drivers an optional hook to implement
+       // this in a more efficient or more reliable way, if they
+       // have one.
+       c, err := db.conn()
+       if err != nil {
+               return err
+       }
+       db.putConn(c, nil)
+       return nil
+}
+
 // Close closes the database, releasing any open resources.
 func (db *DB) Close() error {
        db.mu.Lock()