# @baz-scm/pgmq-ts 中文文档

规范地址：https://npmcn.com/package/%40baz-scm/pgmq-ts/

版本：0\.3\.14
npm 元数据更新时间：2026-10-19T07:16:56.566Z
中文译文更新时间：2026-11-07T23:26:09.198Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40baz-scm/pgmq-ts
原文对照：https://npmcn.com/package/%40baz-scm/pgmq-ts/?lang=original
源码仓库：https://github.com/baz-scm/pgmq-ts

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

- 包体积（解压后）：43.1 kB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-10-10T21:02:03.204Z
- 最新版本发布：2026-10-19T07:16:56.152Z
- 近 30 天下载量：2041（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 7 个）

## 中文简介

Pgmq-rs 的打字包装器

## 安装

```sh
npm install @baz-scm/pgmq-ts
```

也可以使用：`pnpm add @baz-scm/pgmq-ts`、`yarn add @baz-scm/pgmq-ts`、`bun add @baz-scm/pgmq-ts`

## README

# PGMQ- TS 导弹

[![npm version](https://badge.fury.io/js/@baz-scm%2Fpgmq-ts.svg)](https://www.npmjs.com/package/@baz-scm/pgmq-ts) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

PGMQ-TS是一个TypeScript库,以PostgreSQL为后端提供消息队列执行. 它相当于pgmq-rs的TypeScript,为在你的Node.js应用程序中执行消息队列提供了一个强而安全的方法.

## 特征

-   🔒 **类型安全**: 完整类型Script支持,并附有信件类型的通用软件
-   🎯 **简单 API**: 队列操作的易用接口
-   📦 **PostgreSQL 备份**: 收发量 PostgreSQL 的可靠性和ACID 属性
-   🔄 **信件可见度**: 信件处理的可配置可见度超时
-   📚 **信件归档**: 已处理信件存档的内置支持
-   🔌 **连接集合**: 有效的数据库连接管理

## 安装

```bash
npm install @baz-scm/pgmq-ts
# or
yarn add @baz-scm/pgmq-ts
# or
pnpm add @baz-scm/pgmq-ts
```

## 快速启动

```typescript
import { PGMQ } from '@baz-scm/pgmq-ts';

// Initialize PGMQ with your PostgreSQL connection string
const pgmq = new PGMQ('postgresql://user:password@localhost:5432/dbname');

// Create the PGMQ schema and a queue
await pgmq.createSchema();
await pgmq.createQueue('my_queue');

// Define your message type
interface MyMessage {
  id: string;
  data: {
    value: string;
  };
}

// Send a message
await pgmq.sendMessage<MyMessage>('my_queue', {
  id: '123',
  data: {
    value: 'Hello PGMQ!'
  }
}, 0);

// Read a message (with 60 second visibility timeout)
const message = await pgmq.readMessage<MyMessage>('my_queue', 60);

if (message) {
  // Process the message
  console.log(message.message); // Access the typed message content
  
  // After processing, either delete or archive the message
  await pgmq.deleteMessage('my_queue', message.msgId);
  // or
  await pgmq.archiveMessage('my_queue', message.msgId);
}
```

## 队列操作

### 创建队列

```typescript
await pgmq.createQueue('my_queue');
```

### 使用队列对象

您也可以为更集中的操作获得一个队列对象:

```typescript
const queue = pgmq.getQueue('my_queue');

// Read messages from the queue
const message = await queue.readMessage<MyMessage>();

// Delete a message
await queue.deleteMessage(messageId);

// Archive a message
await queue.archiveMessage(messageId);
```

### 信件可见度

可见度超时决定了消息在被读取后隐藏的时间. 这使得其他消费者无法在此期间处理同一信息:

```typescript
// Message will be hidden for 60 seconds after being read
const message = await pgmq.readMessage<MyMessage>('my_queue', 60);
```

## 最佳做法

1.  总是定义您信件类型的类型脚本接口
2.  通过调用处理连接清理 `pgmq.end()` 关闭时
3.  根据您的处理需要使用适当的可见度超时
4.  考虑归档重要信件而不是删除
5.  校验队列名称( 仅定义和下划线字符)

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 许可证

这个项目根据麻省理工学院许可证获得许可----详情见LICENSE文件.

## 常见问题

### @baz-scm/pgmq-ts 是什么？

Pgmq-rs 的打字包装器

### 如何安装 @baz-scm/pgmq-ts？

在项目目录运行 npm install @baz-scm/pgmq-ts，或使用 pnpm add / yarn add / bun add。

### @baz-scm/pgmq-ts 支持 TypeScript 吗？

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

### @baz-scm/pgmq-ts 支持 ESM 还是 CommonJS？

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

### @baz-scm/pgmq-ts 可以商用吗？

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

### @baz-scm/pgmq-ts 的下载量有多少？

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

### @baz-scm/pgmq-ts 还在维护吗？

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