Node-Postgres 中 "relation does not exist" 错误分析与解决方案

问题现象

在使用 Node-Postgres 连接 PostgreSQL 数据库时，开发者在执行表创建查询时遇到了一个看似矛盾的错误："relation 'users' does not exist"。这个错误特别令人困惑，因为：

1. 查询语句明确使用了 CREATE TABLE IF NOT EXISTS 语法
2. 表名在代码中被正确前缀化为 cspg_users
3. 相同的查询在 pgAdmin 中执行正常

错误根源分析

经过深入排查，发现这个问题的根本原因在于异步执行顺序问题。具体表现为：

1. 表创建操作在构造函数中启动但未被正确等待
2. 可能存在其他代码路径同时尝试访问尚未创建的表
3. 错误处理机制未能有效捕获异常

关键问题点

1. 构造函数中的异步操作：在类构造函数中直接调用异步方法 makeTables() 而未等待其完成，这会导致后续操作可能在表创建完成前就开始执行。

2. Promise 处理不当：createTable 方法使用了手动构造的 Promise，这种模式在现代 JavaScript 中已不推荐，容易导致错误处理链断裂。

3. 日志记录不足：缺乏足够的执行日志，使得难以追踪查询的实际执行顺序和状态。

解决方案与最佳实践

1. 重构异步初始化

避免在构造函数中直接启动异步操作。推荐采用以下模式：

class DatabaseQueries {
  private pool: Pool;
  private prefix: string;
  private initialized: boolean = false;

  public static async create(): Promise<DatabaseQueries> {
    const instance = new DatabaseQueries();
    await instance.makeTables();
    instance.initialized = true;
    return instance;
  }

  private constructor() {
    this.pool = DatabaseConnection.instance.pool!;
    this.prefix = config.postgres.table_prefix;
  }
}

2. 简化异步代码

将手动 Promise 构造改为 async/await 模式：

private async createTable(tableName: string, columns: string[]): Promise<void> {
  const fullTableName = `${this.prefix}${tableName}`;
  const columnDefinitions = columns.join(', ');
  const query = `CREATE TABLE IF NOT EXISTS ${fullTableName} (${columnDefinitions});`;
  
  try {
    console.debug(`Executing: ${query}`);
    await this.pool.query(query);
    console.debug(`Table ${fullTableName} created successfully`);
  } catch (error) {
    console.error(`Failed to create table ${fullTableName}:`, error);
    throw error;
  }
}

3. 增强错误处理

添加更全面的错误日志记录，包括：

• 查询执行前打印完整 SQL
• 捕获并记录所有可能的错误
• 添加操作状态跟踪

4. 执行顺序保证

确保表之间存在依赖关系时（如外键约束），按正确顺序创建：

public async makeTables(): Promise<void> {
  // 先创建无依赖的表
  await this.createUsersTable();
  
  // 然后创建依赖users表的其他表
  await this.createWebsitesTable();
  await this.createPasswordResetsTable();
}

预防措施

1. 添加初始化状态检查：在所有数据库操作方法中添加初始化验证
2. 使用事务处理：对于多表创建操作，考虑使用事务保证原子性
3. 实施连接池事件监听：监控连接池状态和查询执行情况

总结

"relation does not exist" 错误在 Node-Postgres 使用中常见于异步执行顺序问题。通过重构异步初始化流程、简化 Promise 处理、增强错误日志和完善执行顺序控制，可以有效解决这类问题。关键在于理解 JavaScript 的异步特性和 PostgreSQL 的表依赖关系，确保操作按预期顺序执行。