Postgres.js 插入数据时未生效问题解析

在使用Postgres.js进行数据库操作时，开发人员可能会遇到SQL语句执行成功但数据未实际插入的情况。本文将以一个典型示例分析问题原因并提供解决方案。

问题现象

开发人员编写了如下代码尝试向users表插入两条记录：

async function addUser(){
  const users = [{
    name: 'Murray',
    age: 68,
  },
  {
    name: 'Walter',
    age: 80
  }]
  
  let res = await sql`insert into users ${ sql(users) }`.describe();
  console.log(res);
  return 'add success'
}

控制台输出显示SQL语句已正确生成：

{
  string: "insert into users (\"name\",\"age\")values($1,$2),($3,$4)",
  types: [ 1043, 20, 1043, 20 ],
  name: "ykl9i57au42",
  columns: [],
}

但检查数据库后发现数据并未实际插入。

问题分析

关键在于代码中使用了.describe()方法。在Postgres.js中：

1. .describe()方法用于获取SQL语句的元信息，包括参数类型、返回列等
2. 调用.describe()后不会实际执行SQL语句
3. 该方法主要用于调试和开发阶段了解SQL语句结构

解决方案

要实际执行插入操作，只需移除.describe()调用：

async function addUser(){
  const users = [{
    name: 'Murray',
    age: 68,
  },
  {
    name: 'Walter',
    age: 80
  }]
  
  let res = await sql`insert into users ${ sql(users) }`;
  console.log(res);
  return 'add success'
}

最佳实践建议

1. 生产环境中应避免保留.describe()调用
2. 调试时可先使用.describe()检查SQL结构，确认无误后再移除
3. 对于重要操作，建议添加错误处理逻辑：

try {
  const result = await sql`insert into users ${ sql(users) }`;
  console.log('插入成功，影响行数:', result.count);
} catch (error) {
  console.error('插入失败:', error);
}

通过理解Postgres.js的方法特性，可以避免这类"执行成功但未生效"的问题，确保数据库操作按预期执行。