1. 你需要的其实是服务器准备好了吗,而不是数据库能不能登录先说一个很常见的场景:你在写部署脚本,PostgreSQL刚启动完,下一步要执行迁移或者导入数据。你大概会先想到psql -c select 1,发现连不上,于是脚本里 sleep 10 秒,再重试。运气好没事,运气不好生产环境启动慢,10秒不够,脚本照样崩。pg_isready就是专门解决这个问题的工具。它的职责非常单纯:探测 PostgreSQL 服务器是否已经接受连接。它不做查询、不校验账号密码、不关心业务数据,只回答服务器进程起来了没有、端口通不通、能不能接受新连接。这套逻辑正是你在脚本、容器健康检查、高可用切换、负载均衡探活里真正需要的。它属于 PostgreSQL 官方自带的客户端工具。只要你装了 postgresql-client 相关的软件包,或者用源码编译过 PostgreSQL,pg_isready就跟着一起编译好了,不需要额外安装什么东西。很多人在服务器上用了好几年 PostgreSQL,天天用 psql、pg_dump,却从没注意过这个命令,直到某天排查一个服务明明起来了但脚本一直失败的问题,才发现它有多好用。这篇文章我打算把这几个问题彻底讲清楚:参数怎么用、退出码怎么解读、在什么场景下比 psql 更合适、以及有哪些坑是我实际踩过之后才明白的。最后会给你一套我在生产环境里长期使用的健康检查模板,直接抄作业就行。2. 从参数到退出码,把 pg_isready 的每个细节都拆开看2.1 参数没几个,但每个都有讲究先看最常用的参数组合,不需要安装什么额外依赖,命令本身就是完整的。参数作用示例-h host指定主机地址,可以是 IP、域名、Unix socket 路径pg_isready -h 127.0.0.1-p port指定端口,默认 5432pg_isready -p 5433-d dbname指定数据库名,默认使用 postgres 库pg_isready -d postgres-U username指定连接用户名,默认取当前系统用户pg_isready -U postgres-t timeout连接超时秒数,默认 3 秒pg_isready -t 5-q安静模式,只返回退出码,不输出任何内容pg_isready -q-s在输出中附带系统时间戳,适合写日志pg_isready -s有两个参数很多人容易忽略,一个是-t,一个是-d。-t控制的是连接超时。默认 3 秒,在绝大多数局域网场景下是够的,但如果你要探测的公网地址走的是跨机房线路,或者目标机器负载很高导致 TCP 握手迟迟不能完成,3 秒可能太短。我曾经在监控脚本里遇到过一个诡异现象:手动执行pg_isready明明返回正常,但告警平台每隔几分钟就报一次数据库不可达。后来排查发现是目标服务器某个时间段 CPU 跑满,accept 队列积压,pg_isready的默认 3 秒超时不够用。把超时改到 10 秒之后,问题消失。不要一上来就骂监控平台误报,先看看是不是探测超时太短。-d这个参数容易被忽略,是因为很多人觉得我探测服务器状态,跟指定哪个库有什么关系。实际上 pg_isready 连接时会真正向 PostgreSQL 发送一个 startup 消息,协议层面会带上数据库名和用户名。如果不指定-d,它默认连postgres库;如果postgres库因为某些原因被改坏或删了(虽然很少见),可能会导致探测失败。另外,如果目标库正在执行恢复(recovery),pg_isready 的返回结果也可能是 accepting,需要结合具体业务判断。-s参数我建议在所有写日志的场景里都加上。它的输出会变成这样:2025-01-12 10:23:45.123 UTC 127.0.0.1:5432 - accepting connections没有-s时只有host:port - accepting connections。多了一个时间戳,后续排查日志对齐时间线的时候会省很多事。2.2 退出码 0、1、2、3,每一个都对应一种语义pg_isready 最核心的价值其实不是输出文本,而是退出码。脚本判断靠的就是这个,不是靠人眼去看字符串。退出码含义典型情况0服务器正在接受连接一切正常,PG 进程活着,端口可连接,startup 交互成功1服务器拒绝了连接PG 进程可能活着,但处于拒绝连接的状态,比如还在恢复、max_connections 耗尽、只接受特定来源等2无响应服务器没响应,可能没启动、网络不通、防火墙拦截、超时未握手3没有重试,直接失败参数错误、无法解析主机名、连接被系统层主动拒绝(比超时返回更快),这种通常是配置问题实际使用中,最常见的判断逻辑就两分支:0 就是成功,非 0 就是失败。但如果你做得更精细,1 和 2 能帮你区分服务器起来了但状态不对和服务器根本没起来。举个例子,在主备切换的过程里,备库刚被提升为主库,可能还在执行恢复流程,这时候它对外表现为拒绝连接,pg_isready 返回 1。如果你只是判断非 0 即失败,就会把这个阶段误判为全挂。但如果你知道 1 代表进程活着但不能接待请求,你可以让监控逻辑更聪明一点,比如连续 30 秒返回 1 才告警,短时间的返回 1 可能是切换过程中的正常现象。我在脚本里还喜欢把退出码记录下来,存成状态字段而不是简单记一个 0/1。比如:pg_isready -h 10.0.0.2 -p 5432 -q code$? echo pg_check_status$code这样后面出问题时,能根据当时的退出码反推是在哪个环节挂掉的,而不是只看到失败两个字。2.3 区分把全部参数写对和只写个主机名就完事很多人第一次用 pg_isready 就是pg_isready -h localhost,然后发现返回 accepting connections,以为万事大吉。这个结果不能说错,但它只验证了本机上的 PG 通过默认端口能连通,不代表你的业务连接串也能通。要充分验证,最好把你应用真正用的那套连接参数原样搬过来,包括主机、端口、数据库名、用户名。比如你的 Java 应用用的是jdbc:postgresql://postgres.internal:5432/appdb,那么健康检查就应该写成:pg_isready -h postgres.internal -p 5432 -d appdb -U appuser -t 5 -s这样测出来的ready,才是跟你业务通道真正一致的 ready。别用localhost自欺欺人,应用连的是内网域名,你的监测工具也得连同一个域名。3. 实战现场:脚本、容器、HA 切换里都是它的主场3.1 一个完整的等待就绪脚本最常见的需求是:容器或者服务刚启动,脚本要等 PostgreSQL 就绪后再执行初始化。下面这个脚本是我用了一年多的模板,直接可以用,主要逻辑是循环探测、记录日志、超时退出:#!/usr/bin/env bash set -euo pipefail PG_HOST${PGHOST:-127.0.0.1} PG_PORT${PGPORT:-5432} PG_USER${PGUSER:-postgres} PG_DB${PGDATABASE:-postgres} TIMEOUT${PG_READY_TIMEOUT:-60} INTERVAL2 echo [$(date %F_%T)] waiting for postgres at ${PG_HOST}:${PG_PORT}... start_time$(date %s) while true; do if pg_isready -h $PG_HOST -p $PG_PORT -d $PG_DB -U $PG_USER -q; then echo [$(date %F_%T)] postgres is accepting connections exit 0 fi elapsed$(( $(date %s) - start_time )) if [ $elapsed -ge $TIMEOUT ]; then echo [$(date %F_%T)] timeout after ${TIMEOUT}s, postgres not ready 2 exit 1 fi sleep $INTERVAL done这里有个细节值得说:-q和echo的组合。如果不用-q,每次循环都会打一行 host:port - no response,日志会被刷屏;用-q以后,只有最终成功或超时才输出一行。但代价是中间过程的沉默,如果卡了很久才超时,你不好判断是循环卡住了还是正常等待。所以我个人在实际部署时往往会去掉-q,改成每次失败只打一行短日志,方便观察进度,代价只是日志多几行,完全可以接受。另一个是被很多人忽视的细节:循环间隔INTERVAL不要设成 0.5 秒以内的激进值。PG 启动时会经历 postmaster 进程起来、共享内存初始化、WAL 恢复、监听 socket 绑定这几个阶段,这些阶段通常是毫秒级完成的,但如果你是重启一个很大的实例,恢复可能持续几十秒。你隔 0.5 秒就去探一次,除了把监控日志刷死之外没有任何意义。2 到 3 秒的间隔是合理的,如果再配合超时总时长,已经完全够用。3.2 Docker 与编排平台:pg_isready 就是天生为健康检查准备的如果你用 Docker 跑 PostgreSQL,官方镜像里同时带了 psql 和 pg_isready。在docker-compose.yml里,最常见的健康检查写法是这样:services: postgres: image: postgres:16 environment: POSTGRES_USER: appuser POSTGRES_PASSWORD: secret POSTGRES_DB: appdb healthcheck: test: [CMD-SHELL, pg_isready -U appuser -d appdb -h 127.0.0.1 -p 5432] interval: 5s timeout: 3s retries: 5 start_period: 10s有几个重点需要展开。start_period参数很关键。它表示容器启动后,给应用多长时间的宽限期,在宽限期内健康检查失败不会立刻按 retries 判定 unhealthy。PostgreSQL 容器首次启动要做初始化,可能要生成配置文件、创建用户、初始化数据目录,这个时间通常不超过 10 秒,但如果你的数据目录很大或者要做恢复,可能需要更久。把 start_period 稍微调大,可以避免容器初始化慢导致业务编排平台反复重启数据库的尴尬问题。interval建议 5 到 10 秒,timeout用 3 秒基本上合适,但如果你的数据库容器和探活容器之间有网络波动,可以把 timeout 调到 5 秒。注意 timeout 必须小于 interval,否则上一次探测还没结束,下一次就开始发了,不是致命问题,但日志会乱。再强调一下,健康检查里一定要把test写成像启动就绪检查那样完整,而不是只写pg_isready三个字。默认不加-h时,pg_isready 会尝试 Unix socket 和 localhost。在容器内,这两个路径通常都通,但为了明确、可控,我建议把主机地址写清楚。127.0.0.1 是最稳妥的一层,因为它是本容器内的 PG 进程在监听,不经过任何外部网络设备。在编排环境里使用 pg_isready,还有一个非常实用的设计:把它放在独立的基础镜像里当探针工具。比如 Kubernetes 的 sidecar 模式里,用一个装了 postgresql-client 的轻量镜像作为 migration job 的探针容器,主业务容器完全不装 psql。这样业务镜像可以做得更小,同时探针逻辑和真实连接路径完全一致。3.3 高可用切换场景:别让探活把你带进沟里在高可用架构里,比如 Patroni、repmgr 或自研的主备切换系统,pg_isready 通常是探活链路的第一环。它回答这个节点能不能连,后面往往还有第二环——比如查询pg_is_in_recovery()来判断这是我备库还是主库。我自己在维护一组 PostgreSQL 集群时遇到过这样的怪事:监控显示某个节点 pg_isready 正常,但应用连接经常失败。最后定位到,那台机器的 PostgreSQL 配置了pg_hba.conf只允许特定来源访问,而我的监控机器明明不在白名单里,却因为数据库里配置了trust认证,导致 pg_isready 能建立连接,但业务账号用密码登录时被 hba 规则拒绝。也就是说,pg_isready关心的是 TCP 层能否连上并完成 startup 握手,它不关心认证是否通过。很多人不知道这个点,在排查问题时被它误导。具体场景:如果你把pg_hba.conf里的规则搞错了,业务账号登录全部失败,但 pg_isready 即使不指定用户、不提供密码,照样返回 accepting connections。因为 PG 在物理连接建立后会先读 startup 消息,其中包含数据库名和用户名,如果 hba 配置为trust,连接直接放行;如果配置为md5或scram-sha-256,在认证成功之前,pg_isready 其实已经退出了——它只是探测服务器状态,不参与后续的认证握手。所以,HA 切换的探活不能只依赖 pg_isready。至少要加一层真实业务账号能不能登录的探测。我常用的第二层是:psql postgresql://${REAL_USER}:${REAL_PASSWORD}${PG_HOST}/${PG_DB} -c select 1 /dev/null注意,这一层不能频繁跑,因为它涉及完整认证和查询,频率太高会额外消耗服务器资源,一般做成 10 秒或 30 秒一次。而 pg_isready 可以做到 2 到 3 秒一次,因为它的开销极低。3.4 把 pg_isready 塞进 cron 的注意事项用 cron 定期执行 pg_isready 也是一类常见玩法,但要小心一个问题:默认情况下,pg_isready 在无参执行时,主机名取的是环境变量PGHOST,没设的话尝试 Unix socket,再不行才去连 localhost。如果你在 cron 环境里写pg_isready不加任何参数,可能因为当前用户的 shell 环境里根本没设置这些变量,导致它去尝试一个并不存在的 socket 路径,然后返回 2。这不是工具的问题,是环境变量作用域的问题。所以 cron 任务里的命令,务必写成全参形式:*/5 * * * * /usr/bin/pg_isready -h 127.0.0.1 -p 5432 -d postgres -U postgres -s /var/log/pg_isready.log 21另一个点:把-s加上,输出带时间戳,后面你用tail看日志时,对应监控曲线时特别方便。4. 踩坑实录:为什么ready了,业务还是连不上4.1 常见陷阱一:端口的语义被忽略-p参数指定的是 PostgreSQL 监听端口。很多人忽略了一个细节:PostgreSQL 允许在 postgresql.conf 里配置port 5432,但同时也可以用listen_addresses限制监听地址。如果listen_addresses写的是127.0.0.1,那么你用-h 192.168.0.10去探测,即使 port 正确,依然会失败。这看起来像网络不通,实际上是 PostgreSQL 根本没有在那个地址上监听。我排查过一例:运维在云安全组放开了 5432 端口,但 PG 只监听了内网地址,外部探测全超时。当时用 pg_isready 反复测都返回 2,一度怀疑是安全组问题,最后用ss -lnt | grep 5432一看,监听地址根本不对。这类问题用 pg_isready 测不出来的,要配合ss、netstat看真实监听列表。4.2 常见陷阱二:认证配置导致的误判前面说过,pg_isready 不参与认证。这个特性既是优点也是坑。优点:你可以用它快速判断服务器进程本身是否正常,而不需要知道密码。比如 DBA 在凌晨被叫起来排查问题,手头没有应用密码,直接一条pg_isready -h x.x.x.x -p 5432就能拿到最基础的服务器进程是否活着信息。很多年下来,我都习惯第一反应先 pg_isready,而不是去翻密码。缺点:如果业务方告诉我连接失败,我用 pg_isready 一测正常,那我就知道大概率不是网络和进程问题,而是认证、权限、连接池、防火墙策略其中之一。接下来会重点检查pg_hba.conf、用户是否存在、密码是否过期。这个排查路径比无头苍蝇式乱试快得多。4.3 常见陷阱三:超时行为在不同版本里有细微差别PostgreSQL 的客户端工具版本不同,pg_isready 对-t超时行为的处理有细微差别。旧版本里,如果服务器完全没有响应,有时会等待系统 TCP 超时,表现为卡在那里很久才返回 2;新版本默认 3 秒行为更可预期。这也是我为什么建议在脚本里总是显式传-t。如果你要同时管理多套 PostgreSQL 环境,最好让监控端使用的 libpq 版本保持一致。想象一下:同一台监控机上装了多个版本的 postgresql-client,/usr/bin/pg_isready可能来自系统自带的老版本,而你新装的 PostgreSQL 16 自带的 pg_isready 在/usr/lib/postgresql/16/bin/下。版本不一致,参数行为就可能不一致,脚本里最好显式引用完整路径。4.4 数据库名和用户名填错的世界-d填一个不存在的数据库时,pg_isready 会返回什么?这个很多人没试过。实测结果是:它还是会返回 0,只要服务器进程正常接受连接请求,哪怕你指定的数据库名不存在、用户名不存在,启动握手阶段还没到权限校验,它就已经给出accepting connections了。这个结论有点反直觉,但它恰恰说明了 pg_isready 的定位。它不是数据库连通性测试工具,而是服务器状态探测工具。如果你要验证指定的库能不能用指定的账号连上,不能靠 pg_isready,必须回归到 psql 或者其他能走完整认证流程的工具。我在实际项目里会明确分工:pg_isready:检查 PG 进程活着、端口在监听、能完成握手,频率高、开销低。psql:检查认证、权限、目标库可查询,频率低、模拟真实业务路径。应用层探活(比如一个只读接口):检查整个链路,包括业务逻辑,用于最终 SLA 口径的监控。三层缺一不可。5. pg_isready 之外:跟其他探活方式对比,你应该怎么选5.1 psql -c select 1 并非万能探活手段很多人没想到,psql -c select 1在服务器高负载下也可能超时或失败,但这不代表服务器进程真挂了。反过来,select 1成功也不代表一切正常,因为一个数据库可以每分钟成功执行成千上万条 select,却同时因为锁竞争导致写事务全部堆积。所以准确地说,psql 探活的结果,更接近数据库当前能执行简单查询,而 pg_isready 的结果是服务器进程能接受新连接。两者是不同层级的信息。监控系统里应该分层采集,而不是用一个命令包打天下。举个例子,某个 MySQL 转 PostgreSQL 的项目里,同事写了个监控脚本,直接用psql -c select 1,跑了几个月一直正常。直到有一天 PG 发生连接数打满(max_connections 到了上限),psql 的新连接直接被拒,监控立刻报警。但实际上业务连接池早就满了,数据库本身是健康的,真正的问题是连接数配置不合理。这种场景下,如果用 pg_isready 探活,它也会失败,因为新连接被拒了,但它给出的信号仍然是进程活着、无法接受新连接,再配合一个pg_stat_activity查询,一眼就能看出连接数耗尽。5.2 徒手写 TCP 探测 vs pg_isready你自己写一个脚本,用 bash 的/dev/tcp/host/port或 Python 的 socket 来做端口探测,也能判断端口通不通。但它的局限是:端口通,不代表是 PostgreSQL。比如你在同一台机器上装了一个假的监听程序占用了 5432 端口,或者有个代理程序转发 5432,端口探测照样通,但你的应用连上去立刻报错。pg_isready 是通过 PostgreSQL 原生协议发送 startup 消息的,能够确认对端真的理解 PostgreSQL 协议,并且处于接受连接的状态。这两者的可信度差了一个等级。5.3 关于 PostgreSQL 版本和安装方式的一点个人建议从热词里看,很多人正在研究 PostgreSQL 的安装和版本选择。这里顺带聊一个相关的点:我建议生产环境的 PostgreSQL 客户端工具版本,尽量不低于服务器版本,最好保持一致。原因之一就体现在 pg_isready 这样的工具上:老版本客户端对新版本特性不一定完全认知,而新版本客户端对老版本服务器通常兼容得很好。如果你用 Linux 发行版自带的包管理器装 postgresql-client,版本可能落后于服务器。比如服务器已经用 PG 16,而 Ubuntu 自带的是 PG 14 的客户端,这时你做一些故障排查,工具行为会有细微差异。我个人的做法是:使用 PG 官方提供的 apt/yum 源,额外安装对应版本的 postgresql-client 软件包,然后做软链接,统一指向一个路径。这样既能保证工具版本匹配,又能在多版本共存时不混乱。5.4 完美的探活脚本应该长什么样结合前面所有坑和需求,下面是我目前在生产环境使用的探活模板,兼顾了频率、开销和信息量:#!/usr/bin/env bash PG_HOST${1:-127.0.0.1} PG_PORT${2:-5432} PG_APP_DB${3:-appdb} PG_APP_USER${4:-app} PG_APP_PASSWORD${5:-} # 第一层:低频、真实业务账号、真实目标库 psql postgresql://${PG_APP_USER}:${PG_APP_PASSWORD}${PG_HOST}:${PG_PORT}/${PG_APP_DB} \ -tAc select 1 /dev/null 21 if [ $? -eq 0 ]; then echo app-level check ok exit 0 fi # 第二层:高频、无认证依赖、判断服务器进程本身 pg_isready -h $PG_HOST -p $PG_PORT -d postgres -t 3 -s 2 code$? if [ $code -eq 0 ]; then echo server is ready, but app-level login failed (auth/connection config issue?) 2 exit 1 fi # 第三层:彻底不可达 echo server not reachable, pg_isready exit${code} 2 exit 2这个脚本的核心思想是:优先模拟真实业务路径;如果真实路径失败,再降级到 pg_isready 判断是数据库本身问题还是应用配置问题。配合监控平台,你可以把不同的退出码映射成不同的告警优先级。实际运行过一次你就会发现,它的输出非常有信息量。数据库进程挂了时,第二层会给出 no response;数据库正常但密码配置错了时,第一层失败第二层成功,提醒你去看应用的连接配置,而不是把所有问题都归到数据库故障上。6. 写在最后的几个小习惯我不是那种喜欢收藏一堆命令然后从不落地的人,pg_isready 之所以值得单独写一篇,是因为它确实帮我在多次故障排查里省下了大把时间。你只要记住三件事:第一,所有脚本里给 pg_isready 显式传-t。默认 3 秒在云上和跨机房环境不一定够用,5 到 10 秒是更稳妥的区间。第二,探活永远分层。pg_isready 是底层探针,psql/业务账号是中间层,应用接口是顶层。哪一层挂了,直接决定你该往哪个方向排查。第三,搞不清状态时,先跑一次pg_isready -h ip -p port -d postgres -s,再跑一次ss -lnt | grep port。这两个命令能帮你快速确定:是进程没起来,还是端口没监听,还是网络层问题。把问题从我觉得数据库有问题收敛到具体环节,故障处理的效率会高非常多。