{
  "id": "php/pdo-query-timeout",
  "signature": "PDOException: SQLSTATE[HY000] [2002] Connection timed out in /var/www/app/src/Database/Connection.php:48",
  "signature_zh": "PDO异常：SQLSTATE[HY000] [2002] 连接超时，位置：/var/www/app/src/Database/Connection.php:48",
  "regex": "PDOException:\\s+SQLSTATE\\[HY000\\]\\s+\\[2002\\]\\s+Connection\\s+timed\\s+out",
  "domain": "php",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "The PDO connection to MySQL fails due to a network timeout, typically because the database server is unreachable, the firewall blocks the port, or the connection pool is exhausted.",
  "root_cause_type": "generic",
  "root_cause_zh": "PDO到MySQL的连接因网络超时而失败，通常是因为数据库服务器不可达、防火墙阻止了端口或连接池耗尽。",
  "versions": [
    {
      "version": "PHP 7.4",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PHP 8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PHP 8.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PHP 8.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MySQL 5.7",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MySQL 8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MariaDB 10.5",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The error is a network-level timeout (MySQL connection timeout defaults to 30 seconds), not a PHP execution time limit. Changing execution time has no effect on the TCP handshake.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "While this can delay the timeout, it may lead to resource exhaustion if the database remains unreachable, and the error will eventually reappear when the connection attempt exceeds the new limit.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Verify network reachability using `telnet db-host 3306` from the PHP server. If it fails, check firewall rules (e.g., `sudo ufw status`) and ensure the MySQL port is open. Also check MySQL's `bind-address` in `/etc/mysql/my.cnf` is set to `0.0.0.0` if remote connections are needed.",
      "success_rate": 0.9,
      "how": "Verify network reachability using `telnet db-host 3306` from the PHP server. If it fails, check firewall rules (e.g., `sudo ufw status`) and ensure the MySQL port is open. Also check MySQL's `bind-address` in `/etc/mysql/my.cnf` is set to `0.0.0.0` if remote connections are needed.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase MySQL connection timeout temporarily: run `SET GLOBAL connect_timeout=60;` and `SET GLOBAL wait_timeout=600;` in MySQL, then update php.ini with `pdo_mysql.default_socket=` and restart PHP-FPM.",
      "success_rate": 0.75,
      "how": "Increase MySQL connection timeout temporarily: run `SET GLOBAL connect_timeout=60;` and `SET GLOBAL wait_timeout=600;` in MySQL, then update php.ini with `pdo_mysql.default_socket=` and restart PHP-FPM.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Verify network reachability using `telnet db-host 3306` from the PHP server. If it fails, check firewall rules (e.g., `sudo ufw status`) and ensure the MySQL port is open. Also check MySQL's `bind-address` in `/etc/mysql/my.cnf` is set to `0.0.0.0` if remote connections are needed.",
    "Increase MySQL connection timeout temporarily: run `SET GLOBAL connect_timeout=60;` and `SET GLOBAL wait_timeout=600;` in MySQL, then update php.ini with `pdo_mysql.default_socket=` and restart PHP-FPM."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.php.net/manual/en/ref.pdo-mysql.connection.php",
  "official_doc_section": null,
  "error_code": "2002",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-11-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}