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

> Understand the Go MySQL driver's checkConnLiveness. Learn its purpose, behavior, and when disabling it can improve performance while managing stale connections.

- Repository: [Go SQL Drivers/mysql](https://github.com/go-sql-driver/mysql)
- Tags: deep-dive
- Published: 2026-03-02

---

**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`](https://github.com/go-sql-driver/mysql/blob/main/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`](https://github.com/go-sql-driver/mysql/blob/main/connection.go). The `ResetSession` function serves as the driver's hook into the connection pool lifecycle, checking the boolean flag before allowing query execution:

```go
// 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`](https://github.com/go-sql-driver/mysql/blob/main/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`](https://github.com/go-sql-driver/mysql/blob/main/dsn.go).

**Via DSN Parameter:**

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

```

**Via Config Struct:**

```go
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`](https://github.com/go-sql-driver/mysql/blob/main/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`](https://github.com/go-sql-driver/mysql/blob/main/connection.go) (`ResetSession`) and [`conncheck.go`](https://github.com/go-sql-driver/mysql/blob/main/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`](https://github.com/go-sql-driver/mysql/blob/main/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.