Docker环境下NestJS连接PostgreSQL失败，需自动创建数据库

问题核心分析 #

你的配置存在三个关键问题导致连接失败，同时需要确保数据库自动创建和服务就绪时机匹配：

1. 容器间通信端口错误：DATABASE_URL里误用了宿主机映射的5431端口，容器内部通信应使用PostgreSQL默认的5432端口
2. API服务启动时机过早：depends_on仅保证PostgreSQL容器启动，不保证数据库服务就绪，导致NestJS连接时数据库还未初始化完成
3. 环境变量格式错误：POSTGRES_PASSWORD与DATABASE_URL写在同一行，导致变量解析异常

分步解决方案 #

1. 修正环境变量文件（.env） #

修复格式和端口错误：

DATABASE_HOST=postgres
POSTGRES_DB=boilerplate
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
DATABASE_URL=postgres://postgres:postgres@postgres:5432/boilerplate
DATABASE_PORT=5432

2. 确保PostgreSQL自动创建数据库 #

你的PostgreSQL服务配置已经通过POSTGRES_DB环境变量指定了要创建的数据库，容器启动时会自动生成boilerplate库。如果之前的./db_data目录存在旧数据，先删除该目录再重新启动，避免残留配置干扰。

3. 让API等待PostgreSQL服务就绪 #

depends_on不等待服务就绪，需添加等待逻辑。这里推荐用wait-on npm包实现：

• 安装依赖：

npm install wait-on --save-dev

• 修改docker-compose.yml中api服务的command：

services:
  api:
    # ... 其他配置保持不变
    command: npx wait-on tcp://postgres:5432 && npm run migration:run && npm run start:dev

该命令会先等待PostgreSQL的5432端口就绪，再执行数据库迁移，最后启动开发服务。

4. 配置NestJS数据库连接重试 #

在TypeORM配置中添加重试机制，进一步避免连接失败：

// src/app.module.ts
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DATABASE_HOST,
      port: parseInt(process.env.DATABASE_PORT),
      username: process.env.POSTGRES_USER,
      password: process.env.POSTGRES_PASSWORD,
      database: process.env.POSTGRES_DB,
      entities: [__dirname + '/**/*.entity{.ts,.js}'],
      migrations: [__dirname + '/migrations/**/*{.ts,.js}'],
      migrationsRun: true, // 自动执行迁移（也可保持手动执行）
      retryAttempts: 10, // 最大重试次数
      retryDelay: 3000, // 每次重试间隔（毫秒）
      synchronize: process.env.NODE_ENV === 'development', // 开发环境自动同步表结构，生产环境禁用
    }),
  ],
})
export class AppModule {}

5. 可选：用Dockerfile添加系统级等待工具 #

如果不想用npm包，也可以在Dockerfile中安装wait-for-it工具：

FROM node:16

WORKDIR /app

COPY package*.json .
RUN npm install
RUN npm install -g ts-node
# 安装wait-for-it工具
RUN apt-get update && apt-get install -y wait-for-it

COPY . .
EXPOSE 3002

然后修改docker-compose.yml的api命令：

command: wait-for-it postgres:5432 -- npm run migration:run && npm run start:dev

验证步骤 #

1. 删除旧的数据库数据目录：rm -rf ./db_data
2. 启动服务：docker-compose up --build
3. 检查日志，确认PostgreSQL输出database system is ready to accept connections后，API再启动并成功连接数据库

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