Docker Compose下Node.js应用无法连接PostgreSQL问题

1. PostgreSQL服务未完全就绪就启动应用 #

depends_on: [postgres]仅能保证PostgreSQL容器先启动，但不代表数据库服务已经完成初始化（比如加载脚本、启动监听端口）。当Node.js应用尝试连接时，PostgreSQL可能还没准备好接受连接，就会抛出连接拒绝错误。

解决办法：

• 在Docker Compose中给PostgreSQL服务添加健康检查，确保服务就绪后再启动应用：

  postgres:
    # 保留原有配置
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  app:
    depends_on:
      postgres:
        condition: service_healthy
    # 保留原有配置
  

• 在Node.js应用中添加连接重试逻辑，避免一次性连接失败：

  const connectWithRetry = async () => {
    try {
      await client.connect();
      console.log("成功连接到PostgreSQL");
    } catch (err) {
      console.log("连接失败，2秒后重试...", err.message);
      setTimeout(connectWithRetry, 2000);
    }
  };
  connectWithRetry();
  

2. 环境变量USER被系统覆盖 #

Linux容器中默认存在USER系统环境变量（对应容器内的当前用户，比如node镜像里的node用户），你设置的USER: postgres会被系统变量覆盖，导致数据库连接的用户名错误，进而引发连接失败。

解决办法：
修改环境变量名，避免和系统变量冲突，比如改成DB_USER：

• Docker Compose的app服务环境变量：

  environment:
    DB_USER: postgres
    HOST: postgres
    DB: postgres
    PASS: postgres
    PORT: 5432
  

• Node.js连接配置：

  const conObject = {
    user: process.env.DB_USER,
    host: process.env.HOST,
    database: process.env.DB,
    password: process.env.PASS,
    port: +process.env.PORT,
    createTableMissing: true,
  };
  

3. 初始化脚本db.sql存在问题 #

挂载的./src/db/db.sql如果有语法错误或者执行失败，会导致PostgreSQL初始化卡住，无法正常提供服务，自然无法接受应用连接。

解决办法：

• 手动执行db.sql脚本，检查是否存在语法错误；
• 查看PostgreSQL容器日志，确认初始化过程是否正常：

  docker logs postgres
  

4. 缺少错误处理导致排查困难 #

当前client.connect()没有错误捕获逻辑，无法准确判断是连接超时、用户名密码错误还是其他问题，只能看到模糊的连接拒绝提示。

解决办法：
给连接添加错误捕获：

client.connect()
  .then(() => console.log("数据库连接成功"))
  .catch(err => console.error("连接错误详情：", err));

内容的提问来源于stack exchange，提问作者Mihailo Tomić