database/sql: add note to Scanner that the database owns values

It was unclear that users must copy values out of the src value
for value types like []byte.

Fixes #24492

Change-Id: I99ad61e0ad0075b9efc5ee4e0d067f752f91b8fa
Reviewed-on: https://go-review.googlesource.com/108535
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/database/sql/sql.go b/src/database/sql/sql.go
index 3a6390d970fc6efe6e391b122cc1ad0a3c92446e..96d7742a3cccaf04fe521a66e04c2bddd64318e4 100644 (file)
--- a/src/database/sql/sql.go
+++ b/src/database/sql/sql.go
@@ -301,6 +301,10 @@ type Scanner interface {
        //
        // An error should be returned if the value cannot be stored
        // without loss of information.
+       //
+       // Reference types such as []byte are only valid until the next call to Scan
+       // and should not be retained. Their underlying memory is owned by the driver.
+       // If retention is necessary, copy their values before the next call to Scan.
        Scan(src interface{}) error
 }