我记得有一次半夜被拉起来处理一个问题新部署的一套应用怎么都连不上 PostgreSQL开发同学说“数据库没起来”我上去一看监听端口是通的psql也能执行查询但应用那边就是报连接失败。折腾了半天才找到原因——连接池先于数据库完成启动应用拿到的是一个“连接可建立但事务不可用”的中间状态。那时候我就在想如果当初有人能在脚本里多加一个 PostgreSQL 自带的诊断工具 pg_isready这个半夜电话根本不会响。这些年我用 pg_isready 的次数估计比psql还多。它不是那种需要专门安装的插件而是 PostgreSQL 官方自带的诊断工具随服务端和客户端一起发布。它的核心功能就一句话检查数据库服务器是否已经准备好接受连接。听起来简单但恰恰是“就绪”这两个字把部署脚本、容器健康检查、主从切换监控这些场景里的痛点全解决了。这篇文章我会从最基础的用法讲起然后给出参数和退出码的完整语义再结合部署脚本、Docker、K8s 等真实场景把我踩过的坑和绕过的弯一并说清楚。无论你是刚入门的 PostgreSQL 用户还是写自动化脚本的老手都应该能从中得到一些可复用的经验。1. 没有 pg_isready 的日子里我都在用什么土办法1.1 那些看似能用、其实很别扭的替代方案如果你是从 PostgreSQL 9.x 时代走过来的应该知道那时候想判断“数据库到底能不能连”最朴素的方法就是telnet ip 5432。端口通了就认为没问题端口不通就认为没起来。现在回头看这个判断太粗暴了端口通只能说明某个进程在监听但不能说明这个进程就是 PostgreSQL更不能说明数据库已经完成启动、可以正常读写事务了。你可能连到一个正在崩溃恢复中的实例TCP 握手是成功的但真正跑查询时就会报“数据库系统正在启动”或者“正在恢复中”。后来有人改用nc -z本质还是 TCP 层探测和 telnet 没有区别。再后来有人直接用psql跑SELECT 1这个确实能确认服务完整可用但代价很大它要走完整个认证流程意味着你必须提供用户名、密码还得处理pg_hba.conf里的认证策略。如果在自动化脚本里硬编码密码安全上就埋了雷如果服务器配置了 SSL你还要额外处理证书验证。一个简单的“探活”动作被搞得越来越重。还有一种是本机执行pg_ctl status只能用在数据库和脚本在同一台机器、且知道数据目录路径的场景。一旦数据库跑在远程或者你用的是托管实例这条路就行不通了。1.2 pg_isready 的设计哲学只做探活不做认证pg_isready 高明的地方在于它刻意把“探活”这件事做得非常窄。它不查用户名密码不做认证甚至不需要指定数据库名——它只是建立一个底层连接然后看服务器是否响应“接受连接”的信号。这就好比你要确认一栋楼里有没有人在办公不需要真的走进去谈一单生意只要看窗户亮着灯、门能推开就够了。它不需要你拥有这栋楼的钥匙。这个设计的直接好处有三个第一不需要密码脚本里不会出现敏感信息第二不依赖本机文件可以随意远程探测第三速度快、开销低每次探测只建立最小的握手非常适合高频调用。我从 PostgreSQL 10 开始把这个工具用在了几乎所有自动化流程里再也没回头用那些土办法。它虽然不能替代真正的业务连通性验证但在“判断实例是否就绪”这个特定问题上它是目前最贴近需求、最轻量的选择。2. 参数和退出码pg_isready 的完整使用手册2.1 常用参数速查pg_isready 的参数不算多但每个都很实用。先给出一份速查表然后挑几个重点展开。参数作用默认值-h host指定服务器主机名或 IP默认走环境变量或本地 socket-p port指定端口号默认5432或环境变量 PGPORT-d dbname指定数据库名用于连接尝试不指定也能探测-U username指定用户名默认当前系统用户-t seconds连接超时时间支持小数默认 3 秒-q静默模式不输出文字只返回退出码无-s针对主库/备库角色的状态检查新版本无这里我想重点提醒-t参数。我之前犯过一个低级错误在一个发布脚本里直接写pg_isready -h db-server没有加超时。正常情况下 3 秒就返回了但有一次数据库服务器网络闪断TCP 连接迟迟无法建立脚本就硬生生卡在那里。后来查文档才发现默认超时不是“无限”而是 3 秒但如果你在-t 0或者某些网络栈异常的情况下行为会变得不可预期。所以我的习惯是永远显式指定超时比如-t 2甚至-t 0.5让脚本的节奏完全可控。-d参数有点容易被忽略官方文档说它“用于连接尝试”意思是它不一定非要填写。但在某些特殊场景下比如服务器的认证策略针对不同数据库有不同的行为时指定一个存在的库名能让探测结果更准确。我通常会在探测命令里带上一个确定存在的库名比如-d postgres避免因为连到默认库时触发了某些奇怪的pg_hba.conf规则。2.2 退出码才是自动化脚本真正读取的东西很多初学者只盯着 pg_isready 的标准输出也就是那句“host:port - accepting connections”但脚本真正要消费的其实是退出码。这个退出码的语义设计得相当清晰我做了个对照表退出码含义典型场景0服务器正在接受连接一切正常1服务器拒绝连接比如不接受外部 IP、认证阶段就拒绝了2没有响应连接超时、端口不通、服务器还没启动3其他无法判断的情况新版本引入比如主机名解析失败这里值得多说一句的是退出码 1 和 2 的区别。退出码 2 通常意味着“根本没有服务在监听”网络层就不通而退出码 1 意味着“有服务响应了但明确表示不接受你的连接请求”。这个区别在排查问题的时候非常重要前者大概率是数据库没启动、端口错误或者防火墙拦截后者则要往监听地址配置、访问控制列表方向去查。我自己的习惯是在脚本里永远不要用标准输出来判断状态因为输出文字的格式在不同版本之间有过变化。你只需要echo $?或者检查 Shell 里的$?值就够了。举个例子pg_isready -h 10.0.0.5 -p 5432 -U postgres -t 5 -q if [ $? -eq 0 ]; then echo 数据库已就绪 else echo 数据库不可用 fi-q静默模式在这里特别有用它让 pg_isready 不打印任何信息完全靠退出码说话脚本拿到的变量干净利落。3. 真实场景里的几种玩法从部署脚本到容器健康检查3.1 部署脚本里的就绪等待我最早把 pg_isready 用起来就是在 CI/CD 发布流程里。以前我们有一个很头疼的问题数据库容器和应用容器是同时启动的应用启动脚本里如果马上执行数据库迁移经常会碰到数据库还没初始化完成psql直接报“无法连接”。后来我封装了一个等待函数核心逻辑就是轮询 pg_isready等退出码变成 0 再继续往下走。wait_for_pg() { local host$1 local port$2 local tries0 until pg_isready -h $host -p $port -d postgres -U postgres -t 2 -q; do tries$((tries 1)) if [ $tries -ge 30 ]; then echo 等待数据库就绪超时 exit 1 fi sleep 2 done echo 数据库已就绪 }注意这里的细节每次探测之间间隔 2 秒最多重试 30 次。如果 60 秒都没起来就直接失败退出避免脚本无限等下去。这套逻辑我在很多项目里复制过配合 systemd 的ExecStartPre或者 CI 流程里的前置步骤非常舒服。另外一个容易忽略的点是如果你在等待过程中使用的是带-q的命令那么循环里最好加上一个日志输出否则一旦数据库迟迟不起来你连“现在执行到哪一步了”都不知道全在那里傻等。3.2 Docker 和 Kubernetes 里的健康检查到了容器化时代pg_isready 的价值更突出了。PostgreSQL 官方镜像里其实自带了这个工具很多人不知道Dockerfile 里也不需要额外安装。我习惯在自定义镜像时保留它因为容器的HEALTHCHECK指令需要的就是这种轻量级探活。HEALTHCHECK --interval10s --timeout5s --retries3 \ CMD pg_isready -U postgres -h localhost -p 5432这个配置会让 Docker 每 10 秒探测一次数据库如果连续 3 次失败容器就会被标记为 unhealthy编排系统可以据此重启容器或触发告警。相比自己在容器里塞一个 ps 脚本或者 curl 端口pg_isready 更符合健康检查的语义它告诉调度器“我不是在测试网络而是在确认真实的数据库实例是否可以接受连接”。Kubernetes 里的用法也类似把 pg_isready 作为readinessProbe的exec命令readinessProbe: exec: command: - pg_isready - -U - postgres - -h - 127.0.0.1 - -p - 5432 initialDelaySeconds: 5 periodSeconds: 10这里我踩过一次坑绝不能省略-h 127.0.0.1直接写-h localhost因为在镜像环境里localhost可能解析到 IPv6 地址::1而 PostgreSQL 默认listen_addresses只监听 IPv4。这会导致一个诡异的现象——端口能通但 pg_isready 一直失败。后面第 4 节我会展开说这件事。3.3 高可用和监控场景如果你是做 PostgreSQL 高可用方案的pg_isready 也经常被拿来当主备切换的探针。比如在做自动故障转移时脚本需要持续观察主库是否还活着如果连续多次返回非 0 退出码就认为主库挂了开始提升备库。这种场景下 pg_isready 的轻量特性很占优势它不会像psql那样在高频轮询时产生大量无谓的认证日志和连接开销。我见过有人直接用 pg_isready 的结果来切换流量但我个人建议如果涉及主备角色判断最好还是查pg_is_in_recovery()这类更精确的函数因为 pg_isready 只能告诉你“服务器是否接受连接”不能告诉你“它是主库还是备库”。只有活性的判断没有角色的判断两者用途不同。当然新版本对这个场景也做了改进这一点放到第 5 节专门讲。4. 使用 pg_isready 时绕不开的几个坑4.1 localhost 解析到 IPv6 导致的诡异失败这个坑我真的印象太深了。有一次帮朋友排查一个 Docker 环境PostgreSQL 在容器里运行健康检查命令是pg_isready -h localhost但无论怎么调都不通过。容器里的服务明明能正常连接日志也显示监听在 5432 端口。最后我进容器里手动执行了一下发现localhost被解析到了::1而 PostgreSQL 的配置只监听了0.0.0.0所以 IPv6 的探测请求根本没有服务端响应。从那以后在所有探测命令里我都写死-h 127.0.0.1或者用-h ::1来专门验证 IPv6 监听。如果你自己写健康检查脚本建议先手动跑一次pg_isready -h localhost和pg_isready -h 127.0.0.1对比一下如果结果不一致基本就是解析顺序的问题。4.2 超时参数没设好脚本会被“卡死”或“误判”前面提到过-t参数我再展开说说。pg_isready 的超时默认是 3 秒但如果你在极端网络环境下使用比如跨公网探测、防火墙丢弃数据包而不是拒绝连接TCP 层的超时可能远不止 3 秒。我遇到过一次防火墙直接 drop 掉 SYN 包的情况pg_isready 等了大概 70 秒才返回当时脚本已经被人以为挂掉了。解决方案很简单显式设置-t并且根据场景选择合适的值。做本机健康检查时我通常用 2 秒以内跨网络探测时用 5-10 秒。还有一种情况是-t 0某些版本里表示无限等待这就要非常小心我基本不用这个值。4.3 输出文字会骗人退出码才是真相这是一个比较隐蔽的问题。Pg_isready 的标准输出有好几种正常时输出 “accepting connections”拒绝时输出 “rejecting connections”没响应时输出 “no response”。看起来很好理解对吧但如果你在脚本里用grep去匹配这些文字就可能出问题。因为不同版本或者不同本地化环境下这些输出文字有可能被翻译成别的语言或者因为服务端信息差异产生前缀变化。我自己就遇到过某个环境里输出的是 “接受连接” 而不是 “accepting connections”导致grep匹配失败脚本误判数据库不可用。后来我把所有依赖输出文本的判断全部改成依赖退出码问题就彻底消失了。记住一件事pg_isready 的退出码才是稳定的契约输出文本只是给人看的不是给脚本用的。4.4 服务端日志会被高频探测刷屏这个坑在低频率使用时几乎无感但如果你把 pg_isready 当成秒级的监控探针就要留意了。当数据库服务器的log_connections参数开启时每次 pg_isready 的探测连接都会在服务端记录一条日志。如果你每 2 秒探一次一天下来日志文件会很可观磁盘空间和日志轮转压力都会上来。我的做法是高频探测场景下要么关闭log_connections要么把探针集中到一台固定的跳板机上并确保日志量可预期。另外pg_isready 不会完成认证所以即便log_connections开启它记录的也只是连接接受信息不会因为密码错误之类的问题产生认证失败日志这一点反而比用psql探测要干净。4.5 连接池后面的“假就绪”最后这个坑比较高级。如果你在应用和 PostgreSQL 之间加了 PgBouncer 这样的连接池那么探测连接池的 pg_isready 结果不能完全代表数据库本身的状态。连接池是活的、接受连接的但后端的 PostgreSQL 实例可能已经在重启。也就是说pg_isready 探测连接池返回 0不代表你真正执行业务 SQL 时不会失败。在这种架构下我的建议是把 pg_isready 同时用在两个层面一个探测连接池保证应用接入点可用另一个探测数据库本体确保数据层真实可用。两者结合才能做出正确的调度判断只看任何一头都容易被误导。5. 版本、获取方式与新版变化5.1 pg_isready 随 PostgreSQL 一起发布不用额外安装很多初学的人以为 pg_isready 是个第三方工具其实它和psql、pg_dump一样都是 PostgreSQL 官方客户端工具的一部分。只要你安装了 PostgreSQL 的服务端完整包或者客户端工具包就一定有这个命令。Ubuntu 上用apt install postgresql-client也能单独拿到它并不需要把整个服务端装一遍。在 Windows 上如果你使用官方图形化安装器pg_isready 会出现在bin目录下和psql.exe放一起。我见过有人在 Windows 上只装了 Navicat 这类图形工具结果想用命令行探活时发现没有 pg_isready这才知道图形工具不会把官方命令行工具带进来。如果你需要做脚本化探活建议去官方下载对应版本的客户端二进制或者直接用包管理器安装 PostgreSQL 客户端组件。5.2 源码编译 PostgreSQL 时的几个注意点结合网上很多人问的“Ubuntu 源码编译 PostgreSQL”我也单独说一下。源码编译完成后pg_isready 会出现在安装目录的bin下。比如你用./configure --prefix/usr/local/pgsql make make install那么工具就在/usr/local/pgsql/bin/pg_isready。它是由src/bin/scripts目录下的源码编译出来的走的是 PostgreSQL 自带 make 流程不需要额外指定目标。编译时经常有人漏掉-Z之类跟压缩相关的选项或者没有安装libreadline-dev、flex、bison这些依赖导致中途失败。我的建议是编译之前先把build-essential、libreadline-dev、zlib1g-dev这些常规依赖装齐然后再执行标准的三步编译。如果你只是想要 pg_isready 这个工具其实没必要整个编译服务端直接下载官方编译好的postgresql-client包会快很多。但如果本来就要编译服务端那就顺手了编完直接就有。5.3 PostgreSQL 18 给了 pg_isready 什么新能力老版本 pg_isready 的语义很单一能连上就是 0连不上就是非 0。这在很多场景下够用但拿来做高可用判断就有局限——你不知道这次连接成功是一个可读写的主库还是一个只读的备库。PostgreSQL 18 版本开始pg_isready 增加了对服务器状态角色的检查能力可以在探活的同时确认当前实例是允许读写连接还是只允许只读连接。这个功能等于把“探活”和“主备角色判断”合并到了一步高可用脚本终于可以不依赖额外的 SQL 查询来判断角色了。我没有在特别早的版本上长期用过这个新特性但测试阶段给我的感受是它保持了 pg_isready 一贯的轻量风格输出和退出码的语义比旧版更丰富适合做主从切换的决策依据。需要提醒的是新参数的命名和行为在不同 RC 版本之间有过调整如果你正在用 beta 版本升级正式版后最好重新读一遍官方文档避免脚本里的参数失效。6. 我在实际使用中最喜欢的一个小技巧最后分享一个我自己的习惯算是对这个工具的一个延伸用法。因为 pg_isready 支持环境变量你可以通过设置PGHOST、PGPORT、PGUSER来隐式传参。在写多环境部署脚本时我喜欢把这些变量写进环境配置文件里脚本本身保持极简export PGHOST10.0.0.5 export PGPORT5432 export PGUSERhealth_check pg_isready -d postgres -t 3 -q这样切环境时只需要改配置不用改脚本逻辑。另外我还会把 pg_isready 的探测结果直接接到监控系统的告警里比如在 Prometheus 的 textfile collector 模式下用一个 cron 任务定期执行 pg_isready 并输出退出码对应的数值这样数据库的“就绪状态”就变成了聚合监控面板上的一条曲线。排查问题时这条曲线配合服务端日志一眼就能看出是网络闪断、认证策略变更还是实例重启导致的不可用。这个工具看起来很小但在我维护过的所有 PostgreSQL 环境里它都是最常被调用、也最不容易出错的命令之一。如果你正在写数据库部署或高可用相关脚本不妨试试把那些重型的psql探测换成 pg_isready你会发现整个流程都轻快了不少。