如何在Node.js中使用pg模块高效操作PostgreSQL数据库？

pg模块是Node.js生态中操作PostgreSQL数据库的首选驱动，它提供了异步非阻塞的API，支持连接池、事务和参数化查询。本文将围绕实际开发中的高频场景，演示如何高效、安全地使用pg模块。

安装与基础连接：快速上手pg模块

安装pg模块非常简单，在项目根目录执行npm install pg即可。模块本身是纯JavaScript实现，底层通过libpq协议与PostgreSQL通信，无需额外编译，因此在Windows、Linux和macOS上都能直接使用。

基础用法是创建Client实例，调用connect方法建立连接，然后使用query执行SQL。下面的代码演示了如何连接本地数据库并获取当前时间：

const { Client } = require('pg');

async function run() {
  const client = new Client({
    host: 'localhost',
    port: 5432,
    user: 'postgres',
    password: 'your_password',
    database: 'testdb'
  });

  await client.connect();
  try {
    const res = await client.query('SELECT NOW() AS now');
    console.log(res.rows[0].now);
  } finally {
    await client.end();
  }
}

run().catch(console.error);

Client适合执行一次性脚本或短生命周期任务，但如果在Web服务中每次请求都new一个Client并connect，会带来明显的连接开销，而且忘记调用end还会导致连接泄漏。下面是一个反面示例：

// 错误示范：连接后未关闭，进程可能无法正常退出
async function badPractice() {
  const client = new Client({
    host: 'localhost',
    port: 5432,
    user: 'postgres',
    password: 'your_password',
    database: 'testdb'
  });
  await client.connect();
  const res = await client.query('SELECT 1');
  console.log(res.rows);
  // 缺少 client.end()
}

正确做法是始终在finally块中调用client.end，确保无论查询是否出错都能释放连接。对于长时间运行的服务，更推荐使用下一节介绍的连接池。

连接池：生产环境的核心配置

连接池的作用是复用数据库连接，避免频繁创建和销毁TCP连接带来的开销。pg模块提供了Pool类，它内部维护一组连接，空闲时保留，繁忙时分配，队列等待。

创建连接池时，需要根据业务并发量和数据库承载能力设置max参数。下面的代码创建了一个最大20个连接的池子，并设置了空闲超时和获取连接超时：

const { Pool } = require('pg');

const pool = new Pool({
  host: 'localhost',
  port: 5432,
  user: 'postgres',
  password: 'your_password',
  database: 'testdb',
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000
});

async function queryUser(id) {
  const res = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
  return res.rows[0];
}

pool.query会自动从池中获取一个连接，执行查询后释放回池子，无需手动管理。注意不要在普通查询场景下使用pool.connect手动获取客户端，除非你需要执行事务或控制事务边界，否则手动获取后忘记release会造成连接耗尽。

连接池运行过程中，空闲连接可能因数据库重启或网络波动被服务端关闭，此时池子会发出error事件。建议监听该事件并做好日志记录，避免进程因未捕获异常而崩溃：

pool.on('error', (err) => {
  console.error('Unexpected error on idle client', err);
  process.exit(-1);
});

连接池的大小并不是越大越好。如果max设置过高，数据库端会承受过多并发连接，可能触发连接数上限；设置过低则请求会排队等待，导致延迟增加。一般建议从10到20起步，通过压力测试逐步调整。

参数化查询与SQL注入防护

SQL注入是Web应用中最常见的安全漏洞之一。如果直接把用户输入拼接到SQL字符串中，攻击者可以构造恶意输入改变查询逻辑。例如下面这个危险写法：

// 危险：字符串拼接
const name = req.query.name; // 用户输入可能是 ' OR '1'='1
const query = `SELECT * FROM users WHERE name = '${name}'`;
const res = await pool.query(query);

上述代码中，如果用户输入一个单引号片段，就能修改SQL语义，导致返回所有用户数据。pg模块提供了参数化查询功能，使用$1、$2作为占位符，将实际值与SQL语句分离：

async function findUserByName(name) {
  const text = 'SELECT * FROM users WHERE name = $1 AND age > $2';
  const values = [name, 18];
  const res = await pool.query(text, values);
  return res.rows;
}

参数化查询由数据库驱动和PostgreSQL服务端共同保证安全，传入的参数会被当作字面值处理，不会参与SQL解析，因此即使参数中包含特殊字符也不会破坏查询结构。需要注意的是，参数占位符只能用于值的位置，不能用于表名、列名或SQL关键字，如果业务需要动态表名，应该使用白名单校验。

此外，pg模块会对JavaScript数组和对象自动序列化为PostgreSQL数组或JSON类型，但在某些场景下建议显式指定类型转换，例如价格比较时加上::numeric，确保数据类型匹配：

const res = await pool.query('SELECT * FROM products WHERE price < $1::numeric', [100]);

总之，任何来自用户的输入都必须通过参数化查询传递，绝不能拼接，这是使用pg模块时必须遵守的底线。

事务处理：保证数据一致性

事务用于将多个数据库操作组合成一个原子单元，要么全部成功，要么全部回滚。典型场景如转账、下单扣库存等。pg模块执行事务需要从连接池中获取一个专用客户端，在该客户端上依次执行BEGIN、SQL操作、COMMIT或ROLLBACK。

下面的代码演示了转账事务，从账户A扣款并向账户B加款：

async function transferMoney(fromId, toId, amount) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const deduct = 'UPDATE accounts SET balance = balance - $1 WHERE id = $2';
    await client.query(deduct, [amount, fromId]);
    const add = 'UPDATE accounts SET balance = balance + $1 WHERE id = $2';
    await client.query(add, [amount, toId]);
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

这里必须使用client而不是pool.query，因为事务要求所有操作在同一个数据库连接上完成，而pool.query每次执行可能分配到不同的连接。client.release必须在finally中调用，确保无论成功失败连接都能归还池子。

对于复杂事务，还可以使用保存点实现部分回滚。保存点允许回滚到事务中的某个标记位置，而不是整个事务。使用SAVEPOINT sp1和ROLLBACK TO sp1即可，但日常开发中用得相对较少。

事务期间如果发生错误，务必捕获并执行ROLLBACK，否则连接会一直处于事务状态，影响后续操作。同时注意事务不宜过长，长时间持有一个连接会降低连接池的整体吞吐量。

流式查询：处理大数据量结果集

当查询结果包含几十万甚至上百万行时，使用pool.query一次性返回所有行会占用大量内存。pg模块配合pg-cursor可以实现流式读取，每次只获取一批数据，处理完再读取下一批。

首先需要安装pg-cursor扩展：npm install pg-cursor。然后从连接池获取客户端并创建游标，使用read方法分批读取：

const Cursor = require('pg-cursor');
const { Pool } = require('pg');

async function streamLargeQuery() {
  const client = await pool.connect();
  const cursor = client.query(new Cursor('SELECT * FROM large_table'));

  function readBatch() {
    cursor.read(100, (err, rows) => {
      if (err) {
        cursor.close(() => client.release());
        throw err;
      }
      if (rows.length === 0) {
        cursor.close(() => client.release());
        return;
      }
      console.log(`处理了 ${rows.length} 行`);
      // 继续读取下一批
      readBatch();
    });
  }

  readBatch();
}

流式查询的优势在于内存占用稳定，不会因为结果集大小而线性增长。但使用游标时必须注意错误处理和客户端释放，否则连接可能悬挂。此外，游标查询在PostgreSQL中会占用服务端资源，处理完成后应尽快关闭游标。

如果使用pg-query-stream结合Node.js流接口，也可以方便地管道化处理数据，但pg-cursor提供了更底层的控制能力，适合需要精确控制批大小的场景。

错误处理与调试技巧

pg模块的异步方法返回Promise，因此推荐使用async/await配合try-catch捕获错误。常见的错误类型包括连接超时、SQL语法错误、约束冲突等。错误对象通常包含code和detail字段，可以用来区分具体原因。

下面是一个带错误分类的查询函数：

async function safeQuery(text, values) {
  try {
    const res = await pool.query(text, values);
    return res.rows;
  } catch (err) {
    if (err.code === '23505') {
      console.error('唯一约束冲突');
    } else if (err.code === '23503') {
      console.error('外键约束冲突');
    } else {
      console.error('查询失败:', err.message);
    }
    throw err;
  }
}

调试SQL问题时，可以在连接配置中设置debug: true，或者在执行前打印SQL语句和参数。pg模块会输出详细的协议交互日志，帮助定位慢查询和错误。生产环境建议记录慢查询日志，并结合PostgreSQL自带的pg_stat_statements扩展分析性能瓶颈。

总结

pg模块是Node.js连接PostgreSQL最成熟、最灵活的选择。掌握基础Client、连接池、参数化查询、事务和流式查询，能够覆盖绝大多数业务场景。在编码时牢记三点：连接用后即还、参数永不拼接、事务必须释放连接。这样就能避免常见坑，写出稳定高效的数据库访问代码。

Node.jsPostgreSQLpg模块修改时间：2026-09-22 19:30:37