PostgreSQL容器就绪检查：pg_isready最佳实践

1. 为什么需要等待PostgreSQL就绪？

在容器化部署和自动化脚本中，我们经常遇到一个典型场景：当PostgreSQL容器启动后，立即执行数据库迁移或初始化脚本时，可能会遇到连接失败的错误。这是因为数据库服务虽然进程已启动，但内部初始化（如恢复WAL日志、加载扩展等）尚未完成。

我曾在一个Kubernetes项目中踩过这个坑：在Init Container中直接运行psql执行schema初始化，结果有30%的概率失败。日志显示"connection refused"，但实际上Postgres容器已经显示为"Running"状态。这就是典型的"启动但未就绪"现象。

2. 常见等待方案的优劣对比

2.1 简单sleep方案

最直观的做法是使用sleep命令：

bash复制sleep 10  # 等待10秒后再执行操作

问题在于：

• 固定等待时间难以适配不同环境（开发机可能3秒就绪，生产环境可能需15秒）
• 资源浪费：如果实例提前就绪，剩余等待时间就是浪费
• 不够健壮：如果实例启动异常，等待期满后仍会失败

2.2 使用psql持续重试

通过psql客户端不断尝试连接：

bash复制until psql -h db -U user -d mydb -c "SELECT 1"; do
  sleep 1
done

缺点：

• 需要配置正确的连接参数（密码、SSL等）
• 会在日志中留下大量连接错误记录
• 可能触发服务器的连接限制告警

2.3 专业工具pg_isready

PostgreSQL官方提供的专用工具：

bash复制pg_isready -h db -p 5432 -d mydb -U postgres

优势：

• 轻量级检查：不建立完整连接，仅检查TCP层和认证准备
• 无需密码：不涉及实际数据库操作
• 明确的状态码：
  • 0：就绪
  • 1：启动中
  • 2：连接失败

3. 生产级就绪检查脚本实现

3.1 基础重试逻辑

bash复制#!/bin/bash

HOST="localhost"
PORT=5432
DB_NAME="postgres"
USER="postgres"
RETRY_MA