Docker中Cron任务连接PostgreSQL触发OperationalError

问题现象 #

基于Dockerfile、docker-compose.yml搭建的周期性任务环境中，执行docker logs -f cron-task时出现连接超时错误：

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server at "db-cron-task" (192.168.32.2), port 5434 failed: Connection timed out
    Is the server running on that host and accepting TCP/IP connections?

解决方案 #

1. 等待数据库完全就绪后启动任务 #

depends_on仅保证容器启动顺序，不会等待数据库服务真正可用。需在启动cron任务前添加数据库就绪检测：
修改docker-compose.yaml中cron-task的command：

command: bash -c "until pg_isready -h db-cron-task -p $POSTGRES_PORT -U $POSTGRES_USER; do sleep 2; done; alembic upgrade head && cron && tail -f /app/logs/cron.log"

利用pg_isready（已通过postgresql-client安装）循环检测，直到数据库就绪再执行后续操作。

2. 修复Cron任务的环境变量加载问题 #

Cron默认不继承容器环境变量，导致任务无法读取.env中的数据库配置。修改Dockerfile中Cron任务定义：

RUN echo '* * * * * . /app/.env && python3 /app/src/main.py >> /app/logs/cron.log 2>&1' > cron-config

每次执行Cron任务时先加载.env文件，确保数据库连接参数正确。

3. 验证数据库端口与配置一致性 #

• 确认.env中POSTGRES_HOST为db-cron-task（Docker服务名，容器间通信依赖服务名）
• 检查docker-compose.yaml中数据库容器的command参数：postgres -c listen_addresses='*' -p $POSTGRES_PORT，确保$POSTGRES_PORT与.env中定义一致
• 进入数据库容器执行netstat -tulpn，确认PostgreSQL正在监听指定端口

4. 处理数据库初始化延迟（首次启动） #

首次启动时数据库需初始化数据卷，即使pg_isready返回就绪，可能仍无法立即接受连接。可扩展检测逻辑：

command: bash -c "until psql -h db-cron-task -p $POSTGRES_PORT -U $POSTGRES_USER -d $POSTGRES_DB -c 'SELECT 1' > /dev/null 2>&1; do sleep 3; done; alembic upgrade head && cron && tail -f /app/logs/cron.log"

直接尝试执行SQL查询，确保数据库完全可用。

内容的提问来源于stack exchange，提问作者Bruno Henrique Peixoto