database/sql: document closing requirements for Stmts
Fixes #8952.
Change-Id: I678f9706eccb5a344eeb0244f45b7b7669830bdc
Reviewed-on: https://go-review.googlesource.com/12204
Reviewed-by: Andrew Gerrand <adg@golang.org>
diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 17afa49..aaa4ea2 100644
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -840,6 +840,8 @@
// Prepare creates a prepared statement for later queries or executions.
// Multiple queries or executions may be run concurrently from the
// returned statement.
+// The caller must call the statement's Close method
+// when the statement is no longer needed.
func (db *DB) Prepare(query string) (*Stmt, error) {
var stmt *Stmt
var err error
@@ -1074,6 +1076,10 @@
//
// After a call to Commit or Rollback, all operations on the
// transaction fail with ErrTxDone.
+//
+// The statements prepared for a transaction by calling
+// the transaction's Prepare or Stmt methods are closed
+// by the call to Commit or Rollback.
type Tx struct {
db *DB
@@ -1209,6 +1215,9 @@
// tx, err := db.Begin()
// ...
// res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
+//
+// The returned statement operates within the transaction and can no longer
+// be used once the transaction has been committed or rolled back.
func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
// TODO(bradfitz): optimize this. Currently this re-prepares
// each time. This is fine for now to illustrate the API but
@@ -1300,7 +1309,8 @@
si driver.Stmt
}
-// Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
+// Stmt is a prepared statement.
+// A Stmt is safe for concurrent use by multiple goroutines.
type Stmt struct {
// Immutable:
db *DB // where we came from
