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!