database/sql: DB.Close documentation is unclear

[toby-dbv]

Go version

go version go1.24.4 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE='on'
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/home/toby/.cache/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/home/toby/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build128873150=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/home/toby/src/dbvisit-standbymp/go.mod'
GOMODCACHE='/home/toby/go/pkg/mod'
GONOPROXY='bitbucket.org/dbvisitsoftware'
GONOSUMDB='bitbucket.org/dbvisitsoftware'
GOOS='linux'
GOPATH='/home/toby/go'
GOPRIVATE='bitbucket.org/dbvisitsoftware'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/home/toby/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.24.4.linux-amd64'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/home/toby/.config/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/home/toby/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.24.4.linux-amd64/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.24.4'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

I read the documentation for database/sql.DB.Close.

What did you see happen?

After reading the documentation for database/sql.DB.Close, I thought that calling Close() on a DB would block waiting for all connections that had been issued from the pool to be returned and closed before it returned. The actual behavior seems to be that the Close() method returns after closing any idle connections and does not block until in-use connections have been closed.

The documentation says:

// Close closes the database and prevents new queries from starting.
// Close then waits for all queries that have started processing on the server
// to finish.
//
// It is rare to Close a [DB], as the [DB] handle is meant to be
// long-lived and shared between many goroutines.

The confusion arises from the phrase "Close then waits".

What did you expect to see?

Assuming the actual behavior of Close is correct (and even if it's not, I don't imagine it can be changed), I'd expect the documentation to make it clear that in-use connections are not closed by the time DB.Close() returns, and possibly explain how the caller could wait for all connections to be closed.

Here are the points that I would like the documentation to make clear:

• Idle connections are closed by the time Close() returns;
• In-progress and future connection requests will return an error (any particular error?);
• In-use connections will complete their work and will be closed later when they are returned to the pool, after Close() returns;
• To wait for all connections to be closed, call DBStats() in a loop waiting for InUse to be zero.

[seankhliao]

cc @kardianos