database/sql: document that Rows.Close must be called

[adonovan]

Failure to call Rows.Close leads to a resource leak. Although the usage example calls defer rows.Close(), it's easy for a caller of, say, QueryContext not to realize that the Rows result is Closeable and to forget to call it.

The documentation of Rows, and any function that returns a Rows, should state that the caller is responsible for calling Close.

Also, the examples suggest that errors from Close may be ignored for read-only queries but should not be ignored for updates. In this respect the database is analogous to a readable or writable file; this too is worth pointing out explicitly.

See also #33938.

[gopherbot]

Change https://golang.org/cl/333989 mentions this issue: database/sql: document that *Rows must be closed after Query