# @cisstech/nestjs-pg-pubsub 中文文档

规范地址：https://npmcn.com/package/%40cisstech/nestjs-pg-pubsub/

版本：1\.15\.2
npm 元数据更新时间：2026-10-29T10:45:49.913Z
中文译文更新时间：2026-11-09T16:56:01.827Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cisstech/nestjs-pg-pubsub
原文对照：https://npmcn.com/package/%40cisstech/nestjs-pg-pubsub/?lang=original
项目主页：https://github.com/cisstech/nestkit/blob/main/libs/pg-pubsub/README.md
源码仓库：https://github.com/cisstech/nestkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：134 kB，45 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：pg ^8\.x，typeorm ^0\.3\.x，pg-listen ^1\.x，@nestjs/core ^10\.x \|\| ^11\.x，@nestjs/common ^10\.x \|\| ^11\.x，@golevelup/nestjs-discovery ^4\.x \|\| ^5\.x
- 首次发布：2025-03-14T02:51:09.038Z
- 最新版本发布：2026-10-29T10:45:49.512Z
- 近 30 天下载量：5828（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 9 个）

## 中文简介

提供 PostgreSQL PubSub 的 NestJS 模块

## 安装

```sh
npm install @cisstech/nestjs-pg-pubsub
```

也可以使用：`pnpm add @cisstech/nestjs-pg-pubsub`、`yarn add @cisstech/nestjs-pg-pubsub`、`bun add @cisstech/nestjs-pg-pubsub`

## README

# @cisstech/nestjs-pg-pubsub (英语)

用于实时 PostgreSQL 的 NestJS 模块,使用触发器和持续队列来更改数据捕获.

[![CI](https://github.com/cisstech/nestkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cisstech/nestkit/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/cisstech/nestkit/branch/main/graph/badge.svg)](https://codecov.io/gh/cisstech/nestkit) [![codefactor](https://www.codefactor.io/repository/github/cisstech/nestkit/badge/main)](https://www.codefactor.io/repository/github/cisstech/nestkit/overview/main) [![GitHub Tag](https://img.shields.io/github/tag/cisstech/nestkit.svg)](https://github.com/cisstech/nestkit/tags) [![npm package](https://img.shields.io/npm/v/@cisstech/nestjs-pg-pubsub.svg)](https://www.npmjs.org/package/@cisstech/nestjs-pg-pubsub) [![NPM downloads](http://img.shields.io/npm/dm/@cisstech/nestjs-pg-pubsub.svg)](https://npmjs.org/package/@cisstech/nestjs-pg-pubsub) [![licence](https://img.shields.io/github/license/cisstech/nestkit)](https://github.com/cisstech/nestkit/blob/main/LICENSE) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

## 它会做什么

PostgreSQL 触发器在您的表格中检测INSERT, UPDATE和DEELTEs. 在队列表格中坚持更改,然后拉出并发送到键入 NestJS 的收听者. 没有只投票的设计, 没有丢失的信息, 没有外部经纪人.

![Diagram](https://npmcn.com/package/%40cisstech/nestjs-pg-pubsub/mermaid.png)

## 为什么这个存在

邮递SQL `LISTEN/NOTIFY` 对实时来说是巨大的,但并不可靠:通知是火灾和遗忘,在断开时丢失,而且有效载荷尺寸有限制。 这个库用耐久的队列把它包起来,这样你就能同时得到反应和保证的交付.

## 密钥属性

-   **持久性**: 通知前在 SQL 表格中持续更改,幸存的崩溃和重新启动
-   **反应**数字 : `LISTEN/NOTIFY` 启动即时处理,以倒计时计费器作为安全网
-   **已订购**:信息由ID处理,分批处理,分批处理 `SELECT FOR UPDATE SKIP LOCKED`
-   **用后退重试**: 失败的消息被重审, 以指数反转(2^{n}$分钟)
-   **后压**: 将同时提交的通知合并在一起,以便最多一次运行一个拉力周期
-   **隔离池**: 使用它自己的 `pg.Pool`,独立于 TypeORM ,以避免集合相争
-   **零下限 DDL**: 触发器是指纹( MD5) , 仅在配置更改时重新创建

## 安装

```bash
yarn add @cisstech/nestjs-pg-pubsub pg
```

支持NestJS v10+和v11+.

## 快速启动

```typescript
// app.module.ts
@Module({
  imports: [
    TypeOrmModule.forRoot({
      /* ... */
    }),
    PgPubSubModule.forRoot({
      databaseUrl: process.env.DATABASE_URL,
    }),
  ],
  providers: [UserChangeListener],
})
export class AppModule {}
```

```typescript
// user-change.listener.ts
@Injectable()
@RegisterPgTableChangeListener(User)
export class UserChangeListener implements PgTableChangeListener<User> {
  async process(changes: PgTableChanges<User>, ctx: PgTableChangeContext): Promise<void> {
    for (const insert of changes.INSERT) {
      console.log(`New user: ${insert.data.email}`)
    }

    for (const update of changes.UPDATE) {
      console.log(`Updated fields: ${update.data.updatedFields.join(', ')}`)
    }
  }
}
```

就是这样。 库自动创建触发器,队列表,并开始收听.

## 如何运作

1.  PostgreSQL 表格更改时触发起火并插入一行 `pg_pubsub_queue`
2.  扳机发出一个 `NOTIFY` 带有频道名称
3.  库收到通知并从队列中取出待发信件
4.  信件发送到匹配 `@RegisterPgTableChangeListener` 类
5.  处理中的信件被标记为这样; 失败的信件被重审, 以指数回放
6.  一个背景传票人每隔60年运行一次 作为安全网 错过通知

### 重要制约因素

-   **听者须快.** 一个慢听者拖延了那张桌子的整个批次. 卸下重活到排队(Bull等),只是从收听者中排出.
-   **使用 `TransactionAdapter` 用于交易性写作.** 如果收听者需要在交易中写入 DB,请配置 `transactionAdapter` 并用它标记听众 `@RegisterPgTableChangeListener(Entity, { transactional: true })`。库将收听器的呼叫包入适配器,通过 `ctx.transaction`。没有适配器,则使用 `ctx.onError` 以信号失败.

## 配置

所有选项都是可选的,但 `databaseUrl`见 [完整配置参考](https://cisstech.github.io/nestkit/docs/nestjs-pg-pubsub/advanced-usage) 详细情况.

密钥调制键 :

| 选项 | 默认 | 它控制着什么 |
| --- | --- | --- |
| `queue.batchSize` | 100个 | 每个拉出周期获取的最大消息 |
| `queue.drainInterval` | 50分钟 | 在排水循环迭接间暂停( DB 呼吸室) |
| `queue.processingTimeout` | 5分钟 | 之后,一个 `processing` 信件被视为孤儿和再审 |
| `queue.concurrency` | 页:1 | 每批并行执行的最大收听器 |
| `queue.awaitInitialPull` | `true` | 启动是否等待初始拉出队列 |
| `transactionAdapter` | \- 说吧 | 在交易中包装听众的 ORM 不可知适配器 |
| `pool.max` | 页:1 | 专用 pg- pubsub 池中的连接 |

## 文档

完整文档: [https://cisstech.github.io/nestkit/docs/nestjs-pg-pubsub/getting-started (中文(简体) )](https://cisstech.github.io/nestkit/docs/nestjs-pg-pubsub/getting-started)

## 许可证

麻省理工学院 [马马杜·西塞](https://github.com/cisstech)

## 常见问题

### @cisstech/nestjs-pg-pubsub 是什么？

提供 PostgreSQL PubSub 的 NestJS 模块

### 如何安装 @cisstech/nestjs-pg-pubsub？

在项目目录运行 npm install @cisstech/nestjs-pg-pubsub，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pg（^8\.x）、typeorm（^0\.3\.x）、pg-listen（^1\.x）、@nestjs/core（^10\.x \|\| ^11\.x）、@nestjs/common（^10\.x \|\| ^11\.x）、@golevelup/nestjs-discovery（^4\.x \|\| ^5\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cisstech/nestjs-pg-pubsub 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cisstech/nestjs-pg-pubsub 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cisstech/nestjs-pg-pubsub 可以商用吗？

@cisstech/nestjs-pg-pubsub 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cisstech/nestjs-pg-pubsub 的下载量有多少？

根据 npm 官方下载统计，@cisstech/nestjs-pg-pubsub 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,828 次，日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cisstech/nestjs-pg-pubsub 还在维护吗？

最新版本 1\.15\.2 发布于 2026/10/29（11 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/03/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。