database/sql: document Stmt lifetime

When prepared on a DB, prepared statement code in database/sql handles everything to keep the prepared statement alive as it moves across the connection pool. Understanding this is an important part of using this API correctly, but it was only documented indirectly via `(*Tx) Prepare*`.

Change-Id: Ic8757e0150d59e675d9f0252f6c15aef2cc2e831
GitHub-Last-Rev: 55dba87
GitHub-Pull-Request: golang#29890
Reviewed-on: https://go-review.googlesource.com/c/159077
Reviewed-by: Brad Fitzpatrick <[email protected]>
Reviewed-by: Daniel Theophanes <[email protected]>

Author: pushrax

src/database/sql/sql.go

@@ -2256,6 +2256,13 @@ var (
 
 // Stmt is a prepared statement.
 // A Stmt is safe for concurrent use by multiple goroutines.
+//
+// If a Stmt is prepared on a Tx or Conn, it will be bound to a single
+// underlying connection forever. If the Tx or Conn closes, the Stmt will
+// become unusable and all operations will return an error.
+// If a Stmt is prepared on a DB, it will remain usable for the lifetime of the
+// DB. When the Stmt needs to execute on a new underlying connection, it will
+// prepare itself on the new connection automatically.
 type Stmt struct {
 	// Immutable:
 	db        *DB    // where we came from