Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
Deleplace opened this issue Mar 22, 2021 · 3 comments
Open

Comments

@Deleplace
Copy link

@Deleplace Deleplace commented Mar 22, 2021

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
Copy link
Author

@Deleplace Deleplace commented Mar 22, 2021

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
Copy link
Author

@Deleplace Deleplace commented Mar 22, 2021

Thanks @tebeka for revealing sql.Named to me.

@cagedmantis cagedmantis changed the title sql: Surface NamedArg in the documentation of various Query funcs database/sql: surface NamedArg in the documentation of various Query funcs Mar 23, 2021
@cagedmantis cagedmantis added this to the Backlog milestone Mar 23, 2021
@cagedmantis
Copy link
Contributor

@cagedmantis cagedmantis commented Mar 23, 2021

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants