# PDO异常：SQLSTATE[HY000] [2002] 连接超时，位置：/var/www/app/src/Database/Connection.php:48

- **ID:** `php/pdo-query-timeout`
- **领域:** php
- **类别:** network_error
- **错误码:** `2002`
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

PDO到MySQL的连接因网络超时而失败，通常是因为数据库服务器不可达、防火墙阻止了端口或连接池耗尽。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| PHP 7.4 | active | — | — |
| PHP 8.0 | active | — | — |
| PHP 8.1 | active | — | — |
| PHP 8.2 | active | — | — |
| MySQL 5.7 | active | — | — |
| MySQL 8.0 | active | — | — |
| MariaDB 10.5 | active | — | — |

## 解决方案

1. ```
   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.
   ```
2. ```
   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.
   ```

## 无效尝试

- **** — 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. (95% 失败率)
- **** — 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. (80% 失败率)