database/sql: surface NamedArg in the documentation of various Query funcs

[Deleplace]

What version of Go are you using (go version)?

$ go version

go version go1.16 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

Not relevant

What did you do?

Used the sql package for years.

What did you expect to see?

I would expect the documentation of funcs sql.{Conn, DB, Stmt, Tx}.{Exec, ExecContext, Query, QueryContext, QueryRow, QueryRowContext} to mention that the variadic argument args ...interface{} behaves specially when an element has type sql.NamedArg.

What did you see instead?

In the absence of more details in the doc of these 24 funcs, I assumed that the variadic argument args ...interface{} was meant to accept only bare values for the formal parameters ? in the query.

The doc for sql.NamedArg and sql.Named does exist, but in years of usage of the sql package I had never stumbled upon them and was not aware that they can be valuable as arguments to the 24 funcs in the Exec family.

So on the one hand, interface{} is not a self-descriptive type name for these things, and the type name is not really something we can fix here. On the other hand, the funcs documentation should mention that they also accept special types like sql.NamedArg, sql.NullString, etc. that will be treated differently. This is something we can fix!

[Deleplace]

I happened to have already used the 6 sql.NullX types for query arguments, and seamlessly enjoyed their special behavior, both for writing and for reading. It was an absolute necessity for me to be able to read and write NULL values, so I naturally discovered these types.

sql.NamedArg is a bit different as I've never written a query that could not be expressed with simple ?s in the query. Now I realize that many queries in my code can be rewritten in a cleaner and more legible way using NamedArgs.

[Deleplace]

Thanks @tebeka for revealing sql.Named to me.

[cagedmantis]

/cc @bradfitz @kardianos