Go MySQL Driver checkConnLiveness: Purpose, Behavior, and When to Disable It

The checkConnLiveness feature in the Go MySQL driver performs a non-blocking socket read via connCheck to detect stale connections before first use, returning driver.ErrBadConn for dead sockets; disabling it reduces syscall overhead in high-performance environments but requires application-level handling of potential stale connections.

The github.com/go-sql-driver/mysql package includes a connection validation mechanism called checkConnLiveness that proactively tests pooled connections before use. This feature, enabled by default, helps prevent cryptic I/O errors by identifying dead sockets early in the request lifecycle. Understanding when to keep or disable this check is crucial for optimizing database performance in Go applications.

What Is checkConnLiveness?

The checkConnLiveness configuration option controls whether the driver validates connection health when retrieving a connection from the pool. When enabled, the driver attempts to detect "stale" or "dead" idle connections before they execute SQL statements.

In connection.go, the (*mysqlConn).ResetSession method implements this logic. If mc.cfg.CheckConnLiveness evaluates to true, the driver invokes the connCheck helper function to probe the underlying network socket. This check occurs only on the first use of a connection after it has been checked out of the pool, precisely when a stale connection would cause the most harm.

How checkConnLiveness Works Under the Hood

The ResetSession Implementation

The entry point for liveness validation resides in connection.go. The ResetSession function serves as the driver's hook into the connection pool lifecycle, checking the boolean flag before allowing query execution:

// Conceptual flow based on connection.go implementation
func (mc *mysqlConn) ResetSession(ctx context.Context) error {
    if mc.cfg.CheckConnLiveness {
        // Returns driver.ErrBadConn if socket is dead
        if err := connCheck(mc.netConn); err != nil {
            return driver.ErrBadConn
        }
    }
    return nil
}

The connCheck Socket Probe

The actual validation logic lives in conncheck.go. The connCheck function performs a non-blocking read on the underlying socket to test for EOF or other error conditions without consuming actual MySQL protocol data:

• If the read returns EOF, the connection is considered dead and unusable
• The function returns driver.ErrBadConn to signal the pool to discard the connection and establish a new one
• This implementation relies on syscall.Conn, making it available only on Linux, macOS, and BSD systems

On unsupported platforms, the check compiles but performs no operation, making the configuration flag effectively irrelevant on Windows or other non-Unix systems.

Configuring checkConnLiveness in Your DSN

The driver exposes this feature through both DSN string parameters and the programmatic Config struct. By default, CheckConnLiveness is set to true according to the struct definition in dsn.go.

Via DSN Parameter:

// Disable liveness checking
dsn := "user:password@tcp(localhost:3306)/dbname?checkConnLiveness=false"
db, err := sql.Open("mysql", dsn)

Via Config Struct:

cfg := mysql.NewConfig()
cfg.User = "user"
cfg.Passwd = "password"
cfg.Net = "tcp"
cfg.Addr = "localhost:3306"
cfg.DBName = "dbname"
cfg.CheckConnLiveness = false  // Explicitly disable

db, err := sql.Open("mysql", cfg.FormatDSN())

The DSN parsing logic in dsn.go handles the checkConnLiveness key at lines 301-307, while the Config struct definition declares the boolean field at lines 64-68.

When to Disable checkConnLiveness

While the default setting provides safety for most applications, specific scenarios benefit from disabling the check:

High-Throughput Performance Optimization

In latency-sensitive services executing thousands of queries per second, the system call overhead of connCheck becomes measurable. Each checkout triggers a non-blocking read and potentially a deadline set on the socket when read timeouts are configured. For applications maintaining persistent connections in healthy network environments, eliminating this overhead can improve throughput.

Controlled Internal Networks

Organizations running database infrastructure behind highly reliable, low-latency internal networks with stable firewall rules may find the check redundant. If idle connections are never silently closed by intermediaries or the server itself, the liveness probe adds overhead without corresponding risk reduction.

Custom Connection Recovery Strategies

Some applications implement sophisticated retry logic or prefer handling stale connections through MySQL's wait_timeout configuration rather than immediate driver-level detection. Disabling checkConnLiveness allows these applications to receive raw I/O errors and apply custom reconnection strategies rather than the standardized driver.ErrBadConn behavior.

Platform-Specific Deployments

Since connCheck requires syscall.Conn support, it functions only on Unix-like systems. On Windows or other unsupported platforms, the flag has no effect, but explicitly disabling it documents the intentional omission of this behavior for cross-platform codebases.

Testing and Simulation Scenarios

Unit tests simulating server failures or connection drops may need to bypass automatic health checks to test higher-level error handling logic. Disabling the feature ensures test scenarios encounter the exact error conditions being validated rather than preemptive connection replacement.

Risks of Disabling Connection Liveness Checks

Caution: Disabling checkConnLiveness removes the driver's automatic detection of dead idle sockets. If the MySQL server closes a connection while it sits idle in the pool (due to wait_timeout, network interruption, or firewall termination), the first subsequent query will fail with a generic I/O error rather than the clean driver.ErrBadConn signal.

Your application must implement robust query retry logic or pool recreation mechanisms to handle these failures gracefully. Without this preparation, users may experience intermittent query failures in production environments.

Summary

• The checkConnLiveness feature in github.com/go-sql-driver/mysql performs proactive socket validation via connCheck before first use of pooled connections
• Implementation spans connection.go (ResetSession) and conncheck.go (platform-specific socket probing)
• Default value is true, configurable via DSN parameter or Config.CheckConnLiveness field
• Disabling benefits high-performance applications with reliable networks by eliminating syscall overhead
• Risk of disabling includes potential stale connection errors on first query rather than preemptive driver.ErrBadConn returns
• Feature is Unix-only; Windows deployments experience no change regardless of configuration

Frequently Asked Questions

What is the default value of checkConnLiveness in go-sql-driver/mysql?

The default value is true. Unless explicitly set to false in the DSN or Config struct, the driver automatically performs liveness checks on every connection checkout from the pool according to the source code in dsn.go.

Does checkConnLiveness work on Windows?

No. The connCheck implementation relies on syscall.Conn, which is only available on Linux, macOS, and BSD systems. On Windows, the check compiles but performs no operation, making the checkConnLiveness flag effectively a no-op regardless of its value.

How does checkConnLiveness affect connection pool performance?

When enabled, each connection checkout incurs a non-blocking socket read system call and potentially a deadline configuration. In high-throughput applications, this adds measurable overhead. Disabling the check eliminates these syscalls, reducing latency for services that maintain stable, persistent connections.

What error does the driver return when checkConnLiveness detects a dead connection?

When connCheck detects a dead socket (typically via EOF), the ResetSession method returns driver.ErrBadConn. This signals the Go database/sql pool to discard the connection and attempt to create a new one before retrying the query.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}