From: Justin Li Date: Wed, 23 Jan 2019 15:15:06 +0000 (+0000) Subject: database/sql: document Stmt lifetime X-Git-Tag: go1.12rc1~5 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=d5a36531b2e0a904d616fec55e64575d6583dd80;p=gostls13.git 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: 55dba87458542cb631baac80aeea0c3607d8f421 GitHub-Pull-Request: golang/go#29890 Reviewed-on: https://go-review.googlesource.com/c/159077 Reviewed-by: Brad Fitzpatrick Reviewed-by: Daniel Theophanes --- diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go index 38a173adba..8cdc903c68 100644 --- 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