MODX PDO persistent connections and MySQL max_connections limits

Question

MODX Revolution utilizes PDO for database interactions, typically opening a fresh connection for each request. However, the pdoPersist configuration option allows for persistent connections, which can reduce the overhead of repeated handshakes during high-traffic periods.

There is uncertainty regarding the stability of persistent connections when the underlying MySQL server reaches its max_connections limit or undergoes a restart. Because the framework does not natively manage a connection pool, persistent sockets may remain open across PHP requests, potentially leading to connection exhaustion without a mechanism to automatically clear stale handles.

For environments running MODX 2.8.x or 3.x, what are the documented behaviors for pdoPersist when the database server terminates a connection? Does the framework provide a way to force a reconnection without restarting the PHP process?

Muntasir · Answer

Confirmed behaviorWhen pdoPersist is enabled and the MySQL server closes a connection (due to max_connections, a restart, or timeout), the persistent PDO resource becomes stale. The next database operation throws a PDOException with messages such as "MySQL server has gone away" or "Lost connection to MySQL server during query". MODX/xPDO does not automatically detect or recycle the stale connection; the exception propagates unless caught by application‑level error handling.Likely explanationPHP’s PDO persistent connections keep the underlying socket open for the lifetime of the worker process. If the server ends the socket, the client‑side resource is no longer valid, but PDO does not ping the server before reuse. Therefore the first query after the failure triggers the error.Steps to recover without restarting PHPEnable exception mode for PDO (default in MODX) or catch PDOException in a custom plugin/error handler.In the catch block, call $modx->connect(); this forces PDO to create a new persistent connection for the current worker.Optionally retry the original operation after the reconnect.

MODX PDO persistent connections and MySQL max_connections limits

1 answer

Confirmed behavior

Likely explanation

Steps to recover without restarting PHP

Your perspective belongs here.

0 question comments