如何解决Docker容器中FastAPI连接PostgreSQL的报错问题

核心问题1：数据库连接地址错误 #

在Docker Compose的默认网络环境中，容器之间通过服务名称通信，而非localhost。你原DB_URL里的localhost会让应用容器尝试连接自身的5432端口，而非PostgreSQL容器。

修复方法：
把DB_URL改成：

DB_URL = "postgresql+psycopg2://postgres:0000@database:5432/store"

这里的database是你Docker Compose里定义的数据库服务名称，Docker会自动将其解析为PostgreSQL容器的IP地址。

核心问题2：数据库未就绪时应用已启动 #

depends_on仅保证PostgreSQL容器比应用容器先启动，但不确保PostgreSQL服务完成初始化并能接受连接。如果应用启动过早，就会出现连接失败。

修复方案（二选一）：

方案1：用pg_isready等待数据库就绪

1. 修改Dockerfile，安装PostgreSQL客户端工具（包含pg_isready）：

# 基于Python镜像的示例
RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client \
    && rm -rf /var/lib/apt/lists/*

2. 调整Docker Compose中app服务的启动命令，加入等待逻辑：

services:
  app:
    # 保留原有配置
    command: sh -c "until pg_isready -h database -p 5432 -U postgres; do sleep 1; done && uvicorn app:app --host 0.0.0.0 --port 8000"

方案2：用wait-for-it脚本

1. 获取wait-for-it.sh脚本，放到项目根目录。

2. 修改Dockerfile，将脚本复制到容器内并赋予执行权限：

COPY wait-for-it.sh /app/wait-for-it.sh
RUN chmod +x /app/wait-for-it.sh

3. 调整Docker Compose中app服务的命令：

services:
  app:
    # 保留原有配置
    command: ["./wait-for-it.sh", "database:5432", "--", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

验证修改 #

重新构建并启动容器：

docker-compose down && docker-compose up --build

此时应用应该能正常连接到PostgreSQL数据库。

内容的提问来源于stack exchange，提问作者Michael Xia