Skip to content

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

Open
@Deleplace

Description

@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!

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationIssues describing a change to documentation.NeedsInvestigationSomeone must examine and confirm this is a valid issue and not a duplicate of an existing one.

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions