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]>
nebulabox · Feb 20, 2019 · 9354c90 · 9354c90
1 parent 19c58d6
commit 9354c90
Showing 1 changed file with 7 additions and 0 deletions.
diff --git a/src/database/sql/sql.go b/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