NestJS+TypeORM+Postgres重启服务器时relation已存在错误排查

我使用NestJS + TypeOrm + Postgres技术栈，碰到一个奇怪的问题：数据库完全干净（无迁移记录、无Schema）时，第一次启动服务，所有迁移执行成功，Schema和表都创建好了。但关闭再重启服务，就会抛出错误：QueryFailedError: relation "prospect" already exists

根本原因分析 #

• 迁移跟踪表未正常工作：TypeOrm默认会在数据库里建migrations表，用来记录哪些迁移已经执行过。如果这个表没创建成功，或者数据库权限不够写不了记录，重启服务时TypeOrm会误以为迁移从没执行过，重复跑创建Schema和表的脚本，自然就会报已存在的错误。
• 大小写与标识符引号问题：PostgreSQL对标识符大小写敏感，你的迁移脚本里用了带双引号的"prospect"."prospect"，但如果实体类里的Schema配置没对应上（比如没加引号、大小写不一致），可能导致TypeOrm尝试在默认Schema下创建同名表，或者迁移记录的标识和实际执行的不匹配。
• 迁移文件路径配置错误：你配置的TYPEORM_MIGRATIONS = dist/src/database/migrations/*.js，如果编译后的迁移文件实际路径和这个配置不匹配，TypeOrm可能找不到已执行的迁移记录，或者重复识别到同一个迁移脚本。
• 数据库search_path冲突：如果数据库用户的默认search_path包含prospectSchema，可能导致执行创建表语句时出现混淆，或者TypeOrm在验证实体时误判表不存在，尝试重复创建。

验证与解决步骤 #

1. 检查migrations表：连接Postgres数据库，看看默认Schema（public）下有没有migrations表，里面有没有prospectInit1626978958486这条记录。如果没有，要么手动创建迁移表，要么检查TypeOrm使用的数据库用户有没有足够权限。
2. 统一标识符配置：确保实体类的Schema和表名配置和迁移脚本完全一致，比如实体类里写@Entity({ schema: 'prospect', name: 'prospect' })，SQL语句里的标识符要么全加双引号，要么全不加（PostgreSQL会自动转小写）。
3. 核对迁移文件路径：确认dist目录下的迁移文件路径和TYPEORM_MIGRATIONS配置匹配，比如编译后的文件是不是在dist/src/database/migrations/下。如果你的编译输出是把src内容直接放到dist根目录，可以把配置改成dist/database/migrations/*.js试试。
4. 检查search_path：执行SHOW search_path;查看当前用户的默认搜索路径，避免和自定义Schema冲突，也可以在TypeOrm配置里明确指定schema选项。
5. 临时修复方案：如果是迁移记录丢失，可以手动往migrations表里插一条记录：

   INSERT INTO migrations (timestamp, name) VALUES (1626978958486, 'prospectInit1626978958486');
   

相关配置与代码 #

ORM配置 #

# ORM VARIABLES
TYPEORM_CONNECTION = postgresql
TYPEORM_HOST = localhost
TYPEORM_USERNAME = test
TYPEORM_PASSWORD = something
TYPEORM_DATABASE = onboarding
TYPEORM_PORT = 5432
TYPEORM_SYNCHRONIZE = false
TYPEORM_MIGRATIONS = dist/src/database/migrations/*.js
TYPEORM_MIGRATIONS_RUN = true
TYPEORM_LOGGING = true
TYPEORM_ENTITIES = src/**/*.entity.ts
TYPEORM_MIGRATIONS_DIR = src/database/migrations

迁移脚本 #

export class prospectInit1626978958486 implements MigrationInterface {
  name = 'prospectInit1626978958486'

  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`CREATE SCHEMA prospect`)
    await queryRunner.query(
      `CREATE TABLE "prospect"."prospect" ("id" uuid NOT NULL DEFAULT uuid_generate_v4(), "external_id" character varying, "createdOn" TIMESTAMP NOT NULL DEFAULT now(), "modifiedOn" TIMESTAMP NOT NULL DEFAULT now(), "deletedOn" TIMESTAMP, "clientFirstName" character varying NOT NULL, "clientLastName" character varying NOT NULL, "clientEmail" character varying NOT NULL, "advisorFirstName" character varying, "advisorLastName" character varying, "advisorEmail" character varying NOT NULL, "advisorRrCode" character varying NOT NULL, "idVerifierFirstName" character varying, "idVerifierLastName" character varying, "idVerifierEmail" character varying NOT NULL, "firmId" character varying NOT NULL, "sendClientEmailNotification" boolean NOT NULL, "onboardingHashedPassword" character varying NOT NULL, "extensors" jsonb, CONSTRAINT "UQ_2cedabc8670a41b3b33fcb93c15" UNIQUE ("external_id"), CONSTRAINT "UQ_2e4c0cd5497385413c0037cb2f6" UNIQUE ("clientEmail"), CONSTRAINT "PK_96a40a8754e69a1ffa6930deb07" PRIMARY KEY ("id"))`,
    )
    await queryRunner.query(
      `CREATE INDEX "IDX_2cedabc8670a41b3b33fcb93c1" ON "prospect"."prospect" ("external_id") `,
    )
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(
      `DROP INDEX "prospect"."IDX_2cedabc8670a41b3b33fcb93c1"`,
    )
    await queryRunner.query(`DROP TABLE "prospect"."prospect"`)
    await queryRunner.query(`DROP SCHEMA prospect`)
  }
}

错误栈详情 #

at TCP.callbackTrampoline (node:internal/async_hooks:130:17) {
  length: 102,
  severity: 'ERROR',
  code: '42P07',
  detail: undefined,
  hint: undefined,
  position: undefined,
  internalPosition: undefined,
  internalQuery: undefined,
  where: undefined,
  schema: undefined,
  table: undefined,
  column: undefined,
  dataType: undefined,
  constraint: undefined,
  file: 'heap.c',
  line: '1164',
  routine: 'heap_create_with_catalog'
}

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