本文介绍利用 postgresql 的 libpq 连接字符串多主机特性，在 php 应用中实现主库宕机时自动故障转移至备库，无需手动轮询或修改业务逻辑，简洁高效且原生支持。
本文介绍利用 postgresql 的 libpq 连接字符串多主机特性，在 php 应用中实现主库宕机时自动故障转移至备库，无需手动轮询或修改业务逻辑，简洁高效且原生支持。
PostgreSQL 自 9.2 起支持 多主机连接字符串（Multi-Host Connection String），这是 libpq 内置的高可用机制，无需额外中间件或应用层重连逻辑。PHP 的 pg_connect()（以及基于 libpq 的 pdo_pgsql 驱动）完全兼容该特性，只需在连接参数中按优先级顺序指定多个主机即可。
✅ 正确配置方式（推荐）
使用逗号分隔的 host 和 port 参数，按连接尝试顺序排列（从左到右），libpq 将依次尝试连接，直到成功建立首个有效连接：
$connectionString = "host=master.db.example.com,slave.db.example.com " .
"port=5432,5432 " .
"dbname=my_institution_db " .
"user=app_user " .
"password=secret " .
"connect_timeout=5";
$conn = pg_connect($connectionString);
if (!$conn) {
throw new RuntimeException("Failed to connect to any database server");
}? 关键说明：
- host=a,b,c 与 port=p1,p2,p3 必须一一对应（数量一致），libpq 将组合为 (a:p1) → (b:p2) → (c:p3) 顺序尝试；
- connect_timeout 建议设为 3–5 秒，避免单点长时间阻塞；
- 所有服务器需使用相同数据库名、用户名和密码（因认证信息全局生效）；
- 故障转移是连接建立时的行为，不涉及运行中连接的动态切换（即已建立的连接不会自动“切回”主库）。
⚠️ 注意事项与最佳实践
只适用于读写分离场景中的“连接入口”：该机制解决的是 初始连接失败 问题，不替代应用层读写分离逻辑。若需将写操作强制发往主库、读操作可走备库，仍需在业务代码中识别角色（例如通过 SELECT pg_is_in_recovery() 判断），本方案仅保障“至少连上一个库”。
主库恢复后不会自动切回：libpq 不维护连接状态池，每次 pg_connect() 都重新执行主机列表遍历。因此，当主库夜间恢复后，后续新连接将自然优先连回主库——无需轮询、无需状态存储、无需定时任务，完全无感。
避免滥用逗号分隔导致意外行为：确保 DNS 解析稳定；若某主机解析失败（如 host=invalid,slave），libpq 可能因解析超时延长整体连接耗时，建议搭配 options='-c statement_timeout=30s' 等安全参数。
-
生产环境增强建议：
- 在连接字符串中添加 target_session_attrs=read-write（PostgreSQL ≥10），可防止误连只读备库（当主库恢复但复制延迟大时，此参数会跳过备库）；
- 使用 PDO 时同样有效：
$dsn = "pgsql:host=master,slave;port=5432,5432;dbname=my_institution_db;user=app_user;password=secret;connect_timeout=5"; $pdo = new PDO($dsn, '', '', [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
✅ 总结
利用 libpq 原生多主机连接能力，是 PHP + PostgreSQL 架构下实现轻量级故障转移的最优解：零依赖、零运维、零轮询开销。它完美契合“夜间关主库但仍需服务”的需求场景——客户端无感知，代码无侵入，部署无变更。唯一前提：确保主备库数据一致性与访问凭证统一。
