# @agendajs/postgres-backend 中文文档

规范地址：https://npmcn.com/package/%40agendajs/postgres-backend/

版本：3\.0\.7
npm 元数据更新时间：2026-10-31T12:57:42.836Z
中文译文更新时间：2026-11-05T21:26:21.774Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agendajs/postgres-backend
原文对照：https://npmcn.com/package/%40agendajs/postgres-backend/?lang=original
项目主页：https://github.com/agenda/agenda#readme
源码仓库：https://github.com/agenda/agenda

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

- 包体积（解压后）：123 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- peer 依赖：agenda 6\.2\.7
- 首次发布：2026-01-26T15:54:04.570Z
- 最新版本发布：2026-10-31T12:57:42.455Z
- 近 30 天下载量：18311（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

PostgreSQL 议程任务调度器后端, 并有 optEN/NOTIFY 支持

## 安装

```sh
npm install @agendajs/postgres-backend
```

也可以使用：`pnpm add @agendajs/postgres-backend`、`yarn add @agendajs/postgres-backend`、`bun add @agendajs/postgres-backend`

## README

# @ agendajs/postgres-后端

PostgreSQL 的后端 [议程项目](https://github.com/agenda/agenda) 在实时工作处理中,有 optEN/NOTIFY 支持的工作调度器.

## 特征

-   议事日程任务的全部 PostgreSQL 存储后端
-   使用 PostgreSQL 倾听/NOTIFY 的实时工作通知
-   具有优化索引的自动创建计划
-   连接集合通过 `pg` 图书馆
-   带有完整类型定义的脚本类型支持

## 安装

```bash
npm install @agendajs/postgres-backend
# or
pnpm add @agendajs/postgres-backend
# or
yarn add @agendajs/postgres-backend
```

## 使用量

### 基本用途

```typescript
import { Agenda } from 'agenda';
import { PostgresBackend } from '@agendajs/postgres-backend';

// Create agenda with PostgreSQL backend
const agenda = new Agenda({
  backend: new PostgresBackend({
    connectionString: 'postgresql://user:pass@localhost:5432/mydb'
  })
});

// Define jobs
agenda.define('send-email', async (job) => {
  const { to, subject, body } = job.attrs.data;
  await sendEmail(to, subject, body);
});

// Start processing
await agenda.start();

// Schedule jobs
await agenda.every('5 minutes', 'send-email', { to: 'user@example.com', subject: 'Hello', body: 'World' });
await agenda.schedule('in 10 minutes', 'send-email', { to: 'other@example.com', subject: 'Hi', body: 'There' });
```

### 配置选项

```typescript
import { PostgresBackend } from '@agendajs/postgres-backend';

const backend = new PostgresBackend({
  // PostgreSQL connection string (required unless pool/poolConfig is provided)
  connectionString: 'postgresql://user:pass@localhost:5432/mydb',

  // Or use pool configuration (creates a new pool)
  poolConfig: {
    host: 'localhost',
    port: 5432,
    database: 'mydb',
    user: 'user',
    password: 'pass',
    max: 20 // max pool size
  },

  // Table name for jobs (default: 'agenda_jobs')
  tableName: 'agenda_jobs',

  // Channel name for LISTEN/NOTIFY (default: 'agenda_jobs')
  channelName: 'agenda_jobs',

  // Name to identify this Agenda instance (stored as lastModifiedBy)
  name: 'worker-1',

  // Whether to create the table and indexes on connect (default: true)
  ensureSchema: true,

  // Sort order for job queries
  sort: {
    nextRunAt: 'asc',
    priority: 'desc'
  }
});
```

### 使用现有池

如果您的应用程序已有 PostgreSQL 连接池, 您可以直接通过 。 游泳池会 **没有** 当议程断开时关闭 :

```typescript
import { Pool } from 'pg';
import { PostgresBackend } from '@agendajs/postgres-backend';

// Your app's existing pool
const pool = new Pool({ connectionString: 'postgresql://...' });

const backend = new PostgresBackend({ pool });

// After agenda.stop(), your pool is still usable
```

## 如何运作

### 存储

后端将工作存储在 PostgreSQL 表格中,其结构如下:

-   `id` - UUID主要钥匙
-   `name` - 职称
-   `priority` - 优先工作(较高=更紧急)
-   `next_run_at` - 当工作应该运行下一个
-   `type` - 工作类型(“ 正常” 或“ 单一” )
-   `locked_at` - 执行分配的锁定时间戳
-   `data` - JSONB工作数据的有效载荷
-   其他元数据字段...

### 实时通知

与MongoDB不同,PostgreSQL通过Listen/NOTIFY拥有内置的酒吧/子. 保存工作时,会向所有倾听《议程》的事例发布通知,立即启动工作处理,而不等待下一次投票间隔.

这意味着:

-   执行职务的延迟度较低
-   减少数据库投票费用
-   二. 有效的跨进程协调

### 分布式锁定

后端使用 PostgreSQL `FOR UPDATE SKIP LOCKED` 以解剖方式锁定工作进行处理,防止在多个《议程》中重复执行.

## 数据库索引

何时 `ensureSchema: true` (默认),创建下列索引:

```sql
-- Main index for finding and locking next job
CREATE INDEX agenda_jobs_find_and_lock_idx
  ON agenda_jobs (name, next_run_at, priority DESC, locked_at, disabled)
  WHERE disabled = FALSE;

-- Index for single jobs (upsert operations)
CREATE UNIQUE INDEX agenda_jobs_single_job_idx
  ON agenda_jobs (name) WHERE type = 'single';

-- Index for locked_at (stale lock detection)
CREATE INDEX agenda_jobs_locked_at_idx
  ON agenda_jobs (locked_at) WHERE locked_at IS NOT NULL;

-- Index for next_run_at queries
CREATE INDEX agenda_jobs_next_run_at_idx
  ON agenda_jobs (next_run_at) WHERE next_run_at IS NOT NULL;
```

## 任务日志

PostgresBackend 包含内置 `PostgresJobLogger` 在专门表格中存储结构化工作生命周期事件(`agenda_logs` (默认情况下). 伐木机是轻量级的,只在第一次使用时创建出它的桌子.

### 自动使用

当您在议事日程中启用日志时, 后端的内置登录器会被自动使用 :

```typescript
const agenda = new Agenda({
  backend: new PostgresBackend({ connectionString: 'postgresql://...' }),
  logging: true  // Uses PostgresJobLogger automatically
});
```

### 独立使用

您还可以使用 `PostgresJobLogger` 独立——例如,在使用不同的后端存储时登录到 PostgreSQL :

```typescript
import { PostgresJobLogger } from '@agendajs/postgres-backend';
import { Pool } from 'pg';

const logger = new PostgresJobLogger({
  pool: new Pool({ connectionString: 'postgresql://...' }),
  logTableName: 'agenda_logs'       // Optional: table name (default: 'agenda_logs')
});

// Use with any backend
import { MongoBackend } from '@agendajs/mongo-backend';
const agenda = new Agenda({
  backend: new MongoBackend({ mongo: db }),
  logging: logger
});
```

见 [议程项目研究](https://github.com/agenda/agenda#persistent-job-logging) 用于完整记录文件.

## 手册Schema 管理

如果您愿意自己管理这个方案( 设置 ) `ensureSchema: false`:

```typescript
import { getCreateTableSQL, getCreateIndexesSQL } from '@agendajs/postgres-backend';

const tableName = 'agenda_jobs';

// Create table
await pool.query(getCreateTableSQL(tableName));

// Create indexes
for (const sql of getCreateIndexesSQL(tableName)) {
  await pool.query(sql);
}
```

## 测试

测试需要一个 PostgreSQL 数据库。 最简单的方法是使用多克:

```bash
# Start PostgreSQL container and run tests
pnpm test:docker

# Or manually:
pnpm docker:up        # Start PostgreSQL container
pnpm test:postgres    # Run tests
pnpm docker:down      # Stop container
```

您也可以使用现有的 PostgreSQL 数据库 :

```bash
POSTGRES_TEST_URL=postgresql://user:pass@localhost:5432/agenda_test pnpm test
```

### 可用的脚本

| 脚本 | 说明 |
| --- | --- |
| `pnpm test` | 运行测试( 需要 PostgreSQL 或 Docker) |
| `pnpm test:postgres` | 用本地 Docker PostgreSQL 运行测试 |
| `pnpm test:docker` | 开始容器,运行测试,停止容器 |
| `pnpm docker:up` | 启动 PostgreSQL 容器 |
| `pnpm docker:down` | 停止 PostgreSQL 容器 |
| `pnpm docker:logs` | 查看容器日志 |

## 所需资源

-   节点.js 18.0.0
-   PostgreSQL 12 (用于 `gen_random_uuid()` 支助)
-   议程项目6.0.0

## 许可证

麻省理工学院

## 常见问题

### @agendajs/postgres-backend 是什么？

PostgreSQL 议程任务调度器后端, 并有 optEN/NOTIFY 支持

### 如何安装 @agendajs/postgres-backend？

在项目目录运行 npm install @agendajs/postgres-backend，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：agenda（6\.2\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agendajs/postgres-backend 支持 TypeScript 吗？

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

### @agendajs/postgres-backend 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agendajs/postgres-backend 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agendajs/postgres-backend 可以商用吗？

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

### @agendajs/postgres-backend 的下载量有多少？

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

### @agendajs/postgres-backend 还在维护吗？

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