MariaDB wait_timeout Explained: Idle Connections, Timeouts, and Best Practices

Introduction

The wait_timeout system variable specifies how long MariaDB keeps an idle non-interactive client connection open before automatically closing it.

When a client connects to MariaDB but remains inactive for longer than the configured timeout, the server releases the connection to free resources. Properly configuring wait_timeout helps prevent excessive idle connections while ensuring applications can maintain stable database communication.

This guide explains how wait_timeout works, how to configure it, recommended values, and common configuration mistakes.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is wait_timeout?

The wait_timeout variable defines how many seconds an idle non-interactive connection may remain open.

View the current value:

SHOW VARIABLES LIKE 'wait_timeout';

Example:

+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| wait_timeout  | 28800 |
+---------------+-------+

The value is measured in seconds.

In this example:

28800 seconds = 8 hours

If a connection remains idle for eight hours, MariaDB automatically closes it.

How It Works

Application
      │
      ▼
Connect
      │
      ▼
Execute SQL
      │
      ▼
Idle
      │
      ├── Activity Before Timeout
      │         │
      │         ▼
      │    Connection Continues
      │
      └── Timeout Reached
                │
                ▼
      Connection Closed

The timer resets whenever the client sends another SQL statement.

Check the Current Value

SHOW VARIABLES LIKE 'wait_timeout';

You can also view both timeout settings:

SHOW VARIABLES
WHERE Variable_name IN
('wait_timeout','interactive_timeout');

Change wait_timeout

Edit the MariaDB configuration.

sudo nano /etc/my.cnf

Example:

[mysqld]

wait_timeout = 600

This sets the timeout to 10 minutes.

Save the file.

Restart MariaDB

Apply the configuration.

sudo systemctl restart mariadb

Verify:

sudo systemctl status mariadb

Expected output:

Active: active (running)

Verify the New Value

SHOW VARIABLES LIKE 'wait_timeout';

Recommended Values

| Environment             | Suggested Value |
| ----------------------- | --------------- |
| Development             |   28800 seconds |
| Personal Website        | 300–600 seconds |
| WordPress               | 300–600 seconds |
| Laravel                 | 300–900 seconds |
| High-Traffic Production | 120–300 seconds |
| API Server              | 120–300 seconds |

The best value depends on your application's connection behavior.

Relationship with interactive_timeout

MariaDB maintains two similar timeout variables.

| Variable              | Applies To                                                   |
| --------------------- | ------------------------------------------------------------ |
| `wait_timeout`        | Non-interactive client connections                           |
| `interactive_timeout` | Interactive sessions such as the MariaDB command-line client |

Most web applications use wait_timeout, while database administrators using the MariaDB console are more likely to be affected by interactive_timeout.

Common Issues

MySQL Server Has Gone Away

Typical error:

MySQL server has gone away

One possible cause is that the connection remained idle longer than the configured wait_timeout.

However, this error can also result from:

Oversized packets

Network interruptions

Server restarts

Client-side connection issues

Always investigate the underlying cause before changing timeout values.

Too Many Sleeping Connections

You can inspect current connections with:

SHOW PROCESSLIST;

Example:

Id   User   Command   Time
15   app    Sleep     950
18   app    Sleep     1020

Large numbers of sleeping connections may indicate:

Connection leaks

Poor connection management

Timeout values that are too high

Timeout Set Too Low

Example:

wait_timeout = 10

Applications with infrequent database activity may find their connections closed unexpectedly, requiring unnecessary reconnections.

Best Practices

Set wait_timeout according to your application's workload.

Monitor sleeping connections using SHOW PROCESSLIST.

Use connection pooling where available.

Close unused database connections in your application.

Avoid excessively long timeout values unless required.

Review timeout-related errors before increasing the setting.

Relationship with Other Variables

wait_timeout works together with several connection-related settings.

| Variable              | Purpose                                |
| --------------------- | -------------------------------------- |
| `interactive_timeout` | Timeout for interactive sessions       |
| `connect_timeout`     | Time allowed to establish a connection |
| `max_connections`     | Maximum concurrent connections         |
| `thread_cache_size`   | Reuses worker threads                  |

Tuning these variables together helps improve connection management and resource utilization.

Related Articles

MariaDB Explained

MariaDB max_connections Explained

MariaDB connect_timeout Explained

MariaDB thread_cache_size Explained

MariaDB max_allowed_packet Explained

Conclusion

The wait_timeout variable determines how long MariaDB keeps idle non-interactive connections open before closing them automatically. Proper configuration helps release unused connections, conserve server resources, and improve overall database stability.

For most production environments, a timeout between 120 and 600 seconds provides a practical balance between efficient resource usage and application reliability. Rather than choosing the longest possible timeout, monitor actual connection behavior and adjust the setting to match your workload.