New Stats Exposed in Go's database/SQL Package

Posted by John Potocny on May 22, 2018 4:18:59 PM

If you’re someone who keeps up with the Go development cycle, then you’ll know that a couple of weeks ago Go entered its feature-freeze for the Go 1.11 release. One of the changes for this upcoming release that caught my eye was to the database/sql package. Daniel Theophanes contributed a change that introduces several new counters available via the DB.Stats() method.


If you’re not familiar with it, DB.Stats() returns a DBStat structure containing information about the underlying sql.DB that the method is called on. Up to this point, the struct has had a single field, tracking the current number of open connections to the database. Daniel’s patch introduces a number of additional fields though:

  • MaxOpenConnections: The max allowed open connections to the DB, as set by DB.SetMaxOpenConns.
  • InUse: The number of connections actively in-use.
  • Idle: The number of open connections that are currently idle.
  • WaitCount: The total number of times that a goroutine has had to wait for a connection.
  • WaitDuration: The cumulative amount of time that goroutines have spent waiting for a connection.
  • MaxIdleClosed: The number of connections closed according to the limit specified by DB.SetMaxIdleConns.
  • MaxLifetimeClosed: The number of connections closed because they exceeded the duration specified by DB.SetConnMaxLifetime.

Note that of the above fields, WaitCount, WaitDuration, MaxIdleClosed and MaxLifetimeClosed are all counters; that is to say, their values never decrease over the lifetime of the DB object, they only increase over time.

The new stats will be available when Go 1.11 is released, which is projected to be available in August. In the meantime, if you aren’t publishing DBStats metrics in your applications today you can work on adding it to integrate into a metrics collector such as Graphite, Prometheus, or even VividCortex. The call to DB.Stats() is cheap and thread-safe, so it’s fairly easy to spawn another goroutine to call it periodically and forward the data to a metrics collector of your choice.

The new information here makes the DB.Stats() command much more useful for monitoring the behavior of database connections. In particular, as noted by Daniel in the commit message, if you see a high amount of waiting or closed connections it may indicate that you need to tune the settings for your DB object. I’ll be adding new metrics to our applications once we upgrade to Go 1.11, you should add them to yours as well!

Can't get enough Go? Check out our free eBook The Ultimate Guide to Building Database-Driven Apps with Go, our free webinar Developing MySQL Applications with Go, or sharpen your skills with the Go database/sql package tutorial

Ready, set, Go!

Recent Posts

Posts by Topic

see all