Repository navigation
database/sql: document what to do on DB.Ping error #23738
Description
The documentation doesn't make clear what to do if we get an error "bad connection".
When Ping returns an error, is it advisable to close the DB object and create a new DB object to replace the old one?
After all, if Ping returns an error, something is clearly wrong.
Is it only the connection that is bad or the pool.
This is how a lot of people are implementing it: https://github.com/pjebs/go-skeleton/blob/master/app/providers/database.go#L61
Activity
[-]closing DB after Ping returns an error[/-][+]database/sql: document what to do on DB.Ping error[/+]kardianos commentedon Feb 8, 2018
I'm not exactly sure what you mean by a "bad pool". How would you tell the difference between an incorrect DSN and a temporary network problem? I think retrying or closing the pool could both be correct.
Glancing at the code you linked concerns me the author is confusing a DB pool with a single connection.
I'm not convinced the docs need clarification, but I can look into it. Maybe we can discuss the pros and cons of each approch, maybe provide a recommendation. There is a direct tie here with how an application comes online (like needing a healthz endpoint or windows service).
AlekSi commentedon Feb 20, 2018
As an author of one Go SQL driver, author of one ORM-ish package, and contributor to numerous other SQL-related Go package, I can say that
database/sqlanddatabase/sql/driverdocumentation can definitely be improved. Specifically, it would be very helpful if documentation for more or all methods and interfaces indatabase/sql/drivermention how returned errors are handled bydatabase/sqlinternals. I don't think that would completely eliminate a need to dig into the code, but at least that documentation can be an explicit contract between the library and third-party drivers.Sorry if it is not very specific. I will create separete specific issues and/or CL when I encounter those issues again.
kardianos commentedon Mar 16, 2018
@AlekSi From what I can see,
database/sql/driverdoes a good job explaining what special errors can be returned by interfaces.However, until go1.10 with the SessionResetter interface, there was no good way to expose normal database errors to users without poisoning the connection pool. Now the story is simple: return the normal custom or wrapped network database error to the user. Then when the ResetSession on the connection is called, return driver.ErrBadConn.
I would love to have a conversation on another issue or https://groups.google.com/forum/#!forum/golang-sql about ways we can improve documentation in specific ways (or find an existing issue). One thing that would probably be helpful is to provide a bare-bones "real" database driver for others to inspect.
gopherbot commentedon Mar 16, 2018
Change https://golang.org/cl/101216 mentions this issue:
database/sql: add more complete examples for opening a DBdatabase/sql: add examples for opening and testing a DB pool