连接超时本质是TCP建立阶段失败，未进入认证或SQL执行；常见于云环境DNS+握手+TLS耗时超设值，需实测后设connect_timeout为2–3倍（最低5秒，跨公网建议10–15秒），且psycopg2必须显式配置，否则可能无限等待。
连接超时不是数据库“慢”，而是 Python 客户端在建立 TCP 连接阶段就卡死了——90% 的情况根本没走到认证或 SQL 执行那步。
connect_timeout 设太小，但网络实际延迟更高
很多同学把 connect_timeout=3 当成“快”，结果在云环境（比如阿里云 RDS 跨可用区、K8s Pod 到数据库 Service）下，DNS 解析 + 三次握手 + TLS 握手轻松吃掉 4–6 秒。一旦超时，pymysql.err.OperationalError: (2003, "Can't connect to MySQL server") 就报出来，且不重试。
- 用
telnet your-db-host 3306或nc -zv your-db-host 3306实测基础连通耗时（不含认证） - 把
connect_timeout设为实测值的 2–3 倍，最低建议 5 秒；生产环境跨公网/跨云建议 10–15 秒 -
psycopg2默认不设connect_timeout，必须显式传，否则可能无限等待
MySQL wait_timeout 和 pool_recycle 没对齐
Flask-SQLAlchemy 或其他 ORM 场景下，连接池里的空闲连接被 MySQL 主动断开（wait_timeout 默认常被云厂商设为 300 秒），但连接池不知道，下次还直接拿出来用，一发 query 就崩出 (2013, 'Lost connection to MySQL server during query')。
- 先查真实值：
SHOW VARIABLES LIKE 'wait_timeout';（别信文档里的 28800） - Flask-SQLAlchemy ≥3.0 必须用
SQLALCHEMY_ENGINE_OPTIONS = {"pool_recycle": 270}（比wait_timeout小至少 30 秒） - 设
pool_recycle=30是自找麻烦：每半分钟重建连接，认证开销压垮数据库
用了 pymssql 却忽略 NTWDBLIB.DLL 缺失问题
Windows 上 import pymssql 成功，但 pymssql.connect() 时卡住几秒后报超时，大概率不是网络问题，而是底层 FreeTDS DLL 加载失败导致连接函数根本没发起。
立即学习“Python免费学习笔记（深入）”；
- 错误现象：无明确异常，只有
OperationalError或静默 hang，日志里看不到 DNS 查询或 TCP SYN - 验证方式：用 Process Monitor 监控 Python 进程是否在找
NTWDBLIB.DLL或freetds.dll - 解法优先级：换
pyodbc（微软官方驱动更稳）；若坚持用pymssql，需手动下载匹配位数的 FreeTDS DLL 并加到 PATH
真正容易被绕开的点是：超时参数只管“连接建立”，不管“连接中间断开”。如果业务里有长事务（比如导出百万行 CSV 后再写入），connect_timeout 和 pool_recycle 都救不了——得靠 read_timeout/write_timeout + 应用层断点续传逻辑。
