SQLSTATE[HY000] [2002] Connection refused when using persistent PDO connections in Phalcon

Answer: The error originates from MySQL, not Phalcon

The SQLSTATE[HY000][2002] Connection refused message is emitted by the MySQL client library when PHP’s persistent PDO connection tries to reuse a socket that the server is no longer accepting. Phalcon merely passes the persistent => true flag to PDO; it does not create or manage a connection pool.

Confirmed facts

• Phalcon’s DI service for db instantiates PDO with the options you provide, including persistent.
• When persistent is true, PHP keeps the underlying socket open across requests in the same SAPI process.
• If the MySQL server reaches its max_connections limit or the socket becomes stale, the next reuse attempt fails with 2002.
• Phalcon does not expose a setting to cap the number of persistent PDO connections per adapter, nor does it provide runtime metrics for those connections.

Likely explanation for intermittent failures

In high‑concurrency, long‑running environments (e.g., PHP‑FPM workers or ReactPHP loops), each worker accumulates its own set of persistent sockets. Over time the total number of sockets held by all workers can approach or exceed MySQL’s max_connections, causing sporadic Connection refused errors.

Steps to diagnose and mitigate (specific to this case)

1. Temporarily disable persistence in your Phalcon DB config ('persistent' => false) and observe whether the errors disappear. This isolates the problem to the persistent‑connection behavior.
2. Verify MySQL reachability with a standalone script:

   <?php
   $pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=test', 'user', 'pass');
   echo $pdo->query('SELECT 1')->fetchColumn();
   ?>
   

   If this fails, check that the MySQL service is running and listening on the given host/port.
3. Check MySQL connection limits: run SHOW VARIABLES LIKE 'max_connections'; and SHOW STATUS LIKE 'Threads_connected';. If Threads_connected regularly nears max_connections, raise the limit or reduce connection usage.
4. Prefer TCP over Unix socket when using persistence: set host to 127.0.0.1 instead of localhost. This avoids issues with stale socket files on some systems.
5. If persistence is required for performance, consider one of the following:
   • Increase max_connections to accommodate the total persistent sockets across all PHP workers.
   • Deploy a lightweight connection proxy (e.g., ProxySQL, MaxScale) that pools connections and presents a stable endpoint to Phalcon.
   • Switch to non‑persistent PDO and rely on PHP’s native request‑lifetime connection overhead, which is usually acceptable for most workloads.
6. Re‑enable persistence only after confirming that MySQL can sustain the expected number of concurrent connections without errors.

Answers to the specific questions

• Undocumented config to limit persistent connections? No. Phalcon does not provide a parameter to cap persistent PDO connections; the limit is governed by PHP’s process‑level persistence and MySQL’s server settings.
• Monitoring hooks or metrics? Phalcon itself does not expose persistent‑connection counts. You must rely on MySQL’s SHOW PROCESSLIST or performance_schema tables, or use PHP extensions like mysqli_get_client_stats (which only works for mysqli, not PDO).
• Recommended approach? If you cannot raise MySQL’s connection limit, disable persistence or place a dedicated connection pooler in front of MySQL. Disabling persistence is the simplest, reliable mitigation; external poolers are advisable only when you need to keep persistence for latency‑sensitive workloads and have control over the proxy.

Missing diagnostic detail that could change the recommendation: Are you connecting via a Unix socket (host=localhost) or TCP (host=127.0.0.1)? Switching to TCP can eliminate socket‑file‑related stale‑connection issues and may resolve the problem without disabling persistence.