# @alma-harness/postgres 中文文档

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

版本：0\.41\.0
npm 元数据更新时间：2026-11-04T12:55:13.788Z
中文译文更新时间：2026-11-06T18:27:14.740Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：435 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@alma-harness/core ^0\.41\.0，@alma-harness/memory ^0\.41\.0，@alma-harness/execution ^0\.41\.0
- 首次发布：2026-08-31T21:23:20.402Z
- 最新版本发布：2026-11-04T12:55:13.504Z
- 近 30 天下载量：2489（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

Alma的Reference Postgres存储适配器:SessionStore和内存存储器(episodes, profile,去除水印),在{org,uid}上键入行级安全.

## 安装

```sh
npm install @alma-harness/postgres
```

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

## README

# @alma-harness/邮递

参考存储适配器 [阿尔玛](https://github.com/FabioFernandesCarneiro/alma), (中文(简体) ), 以行级安全作为防御深度.

> **状况:1.0前.** API仍在移动中;见 [路线图](https://npmcn.com/package/docs/architecture.md#12-adoption-roadmap) 为它的位置.

## 它拥有的

-   `PostgresSessionStore` 谈话日志 一个有栅栏的附子锁住它 接纳会议与会 `FOR SHARE`,活动且在期限之内,或 掷出 `ExecutionStateError` 并写作无( spec: 篱笆- event- appended) . 招生表必须分享其计划,如跑步时间的对.
    
-   `PostgresEpisodeStore`, (中文(简体) ), `PostgresProfileStore`, (中文(简体) ), `PostgresErasureWatermarks` —— 说 记忆层. `alma_memory_facts.retracted_at` 标记被遗忘的密钥( 规格 : 事实追溯; `migrateMemoryStores` 添加,然后再次验证目录.
    
-   `PostgresSpendStore` ——持续预算计数器(谱:花-储存). 租户日计数器是Org键,所以其RLS政策是Org;app 角色不会在两个计数器上被删除 —— 花费在范围清洗后 财务记录.
    
-   `PostgresLegacyTurnClaims` - 仅清除较老的答复 部署。 电线 `createMemoryErasure({ turns })` 当任何历史 声称存在。 它验证范围, 准确比较会话身份并离开 租赁没有改变。 它不能取得、主张、填写、阅读答复或规定 图表。 缺失的表格/出错,而不是报告成功消除. 现有的计划赠款和辅助成员是部署的先决条件. `purgeTurnClaimsBefore` 财务报告和审定财务报表 `purgeExpiredLeases` 保持清晰的历史 单独保留作用下的保留功能,分入限定批次. 清理前查询旧作者;删除 SDK 不停止旧过程.
    
-   `PostgresAuditLog` 5个审计线索(第038段),同步编写 并且没有缓冲包:一个缓冲槽,它失去缓冲 崩溃停止默写, 即失败 `AuditSinkError` 已输入 来抓他 五张表而不是一张 `jsonb` 包,所以"只有元数据,从来没有 内容"是审查者可以审计的一栏. 应用角色得到 `select, insert` 无效 `delete`编号 :`update` ——可以编辑的审计行不是一行. 遗产写作仍然只写作。 已解决的费用范围如下.
    
-   `purgeAuditBefore` 按时间计算,每个家庭(第039项)。 它假设 页:1 `alma_retention` 移徙创造和给予的作用 `select, delete` 在审计表格上,加上对应的 RLS 政策。 这个角色存在 因为应用程序角色故意不能删除 : **切换后可能无法删除 审计行;保留可能,它们是不同的行为者.** 正在扫描 在原始游泳池上,在 dev 中看起来是正确的, 并且删除了任何内容 未作为超级用户连接的部署——FORCE ROW LEVEL 安全主题 即使是桌主到上游.
    
-   `migrateSessionStore`, (中文(简体) ), `migrateMemoryStores`, (中文(简体) ), `migrateSpendStore`, (中文(简体) ), `migrateRoutineRunStore`, (中文(简体) ), `migrateRoutineStore`, (中文(简体) ), `migrateAuditLog` —— 说 一能迁移;运行它们是产品的选择,通常在 启动.
    
-   `PostgresRoutineRunStore` 常规运行为元数据( spec : 邮编: 同样的火,今天的天花板数, 最后交付的散列 对于去dupe, 耐用跨程序。 原子 `claim` 在 RLS 下仲裁执行并提交批次集. 应用程序 角色不被删除——运行记录像线索一样保留——和 `purgeRoutineRunsBefore` 完成的扫描按年数进行作为保留角色, 保存未解决 `running` 财务报告和审定财务报表 `submitted` 记录。 读取一个 结果, 如勾选的开放式提交, 使用自己的索引 ( spec: 常规运行- index); 迁移后再次验证商店的图案. 见 [追回附注](https://npmcn.com/package/%40alma-harness/schedule/README.md#claims-and-recovery)。 。 。 .
    
-   `PostgresRoutineStore` ——常规本身( spec: clock-tick), 如 `jsonb` 根据共同政策; `list` 运行为 `alma_scheduler`,则 角色勾选符假设读取由迁移所创建的每个范围. 把它交给登录的勾选连接,就像其他两个角色一样.
    
-   `PostgresScopeFenceStore` —— 1 schema's 永久瞄准栅(指: 范围。 执行、结果、会话、记忆、常规和常规 运行迁移安装 `alma_scope_fences` (单位:千美元) `BEFORE INSERT` 启动 `alma_executions`, (中文(简体) ), `alma_execution_results`, (中文(简体) ), `alma_session_entries`, (中文(简体) ), `alma_memory_episodes`, (中文(简体) ), `alma_memory_facts`, (中文(简体) ), `alma_routines` 财务报告和审定财务报表 `alma_routine_runs` (光谱:范围-激光); `scopeFenceGateSql(table)` 添加 同样的触发器 到另一个有门的桌子。 触发器拒绝栅栏式瞄准镜的插入,用任意 作者,带有 SQLSTATE `AL001` (单位:千美元)`SCOPE_FENCED_SQLSTATE`页:1 `inScope` 地图 改为 `ScopeFencedError`它拒绝一项未读取的承诺的交易. 应用角色可以选择并插入栅栏,永不更新或删除. 改为: 整个运行时间, 使用 `createPostgresScopeFence` 内 `@alma-harness/runtime/postgres`。 。 。 .
    

每个操作都在交易中运行 假设一个专用 非超级用户作用和约束 `alma.org` 编号 : `alma.uid` 作为本地交易 rLS 策略比较的设置,在一个语句中: `set_config('role', …, true)` 实值 `SET LOCAL ROLE` (规格:交易预告). 应用程序级范围界定 第一层 这是第二层 所以被遗忘了 `WHERE` 无法穿透 租户.

离职使用情况 `checkout(pool)`,倾听 `error` 直到释放: 连接正在死亡 中调拒绝调用,永不杀入过程(spec:check-out-connection-errors). 给自己用吧 `pool.connect()`。 。 。 .

## 升级窗口

迁移更新了上次迁移到的数据库 微小的放出, 重放它们不会改变什么。 更新旧数据库 在阶梯中,每个都位于窗口内(指:升级-窗口).

## 在第一个非超级用户连接之前

`SET LOCAL ROLE alma_app` 只承认连接的登录是 移民组织的成员和任何移民组织都不得给予该成员资格——它不能知道哪些成员是: 登录连接为 。 一次,作为可能赋予的角色(移民) 超级用户会做的:

```ts
await grantRole(pool, { to: "svc_myproduct" });                  // alma_app
await grantRole(pool, { role: "alma_retention", to: "svc_ops" }); // the sweeps, if a different login
```

重新授予是一种不开放的,因此产品在每次启动时都可以运行. 没有它 第一次最不特权的部署失败了 `permission denied to set role` ——故障关闭,一个惊喜 超级用户连接的测试套房 无法看见( 光谱: 擦除- 到达- 要求) .

```ts
import { migrateMemoryStores, PostgresEpisodeStore } from "@alma-harness/postgres";

await migrateMemoryStores(pool);
const episodes = new PostgresEpisodeStore(pool);
```

两个都接受 `statementTimeoutMs` (违约30s)和 `role` ——一个由 模型提供输入需要一个不依赖于调用者的上限 记得一个.

## 永远不能做的事

-   军衔在SQL. 适配器过滤器 _候选人_ 超群的装饰器 匹配 – 把它们交到共享的级别 `@alma-harness/memory`这样 每个后端命令的结果都是一样的.
-   视数据库的校正整理情况而定: 适配器,因为 `ilike` 下级 `lc_ctype=C` 只折叠 ASCII .
-   重释一约. 它证明自己反对 共享套房在 `@alma-harness/testing`因此 `pnpm check:all` 拒绝通过没有 `DATABASE_URL` (第031类).

使用常规警告元数据 `alma_routine_runs.caps_crossed`; 缺席或为空 警告为缺席(请参见:财务警告政策).

## 代办费用结算

运行 `migrateCostSettlementStore(pool)` 在构建前 `PostgresCostSettlementStore(pool)`迁移包括审计/支出计划 设置和添加延展 `alma_audit_cost`; 遗留行保留无结算 身份证被从新书中删除。 赠款 `alma_app` 输入服务登录 如上所述。 受管跑者明确使用这个编剧.

插入一次结算交易递增会话和世界协调时或日总数 一个不可变的收据,并排出每个命名的投影消费者。 之后 不确定行为,只重试同一和解。 输入量变化 `SettlementConflictError`。主机必须在提供者之前坚持身份 发出并保留用于收回的价款用途;这些执行合同是: 此存储适配器未执行 。 永远不要打电话 `AuditLog.cost` 或者说 `SpendStore.add` 同样的罪名.

`pending(scope, consumer)` 返回全部收据,每次通话最多100次。 应用 仅按范围/定居身份,然后打电话 `acknowledge(scope, consumer, id)`。 。 。 . 只有配置主机的消费者才能排出;空列表不会产生任何义务. App角色可以删除待取行,但不能更新/删除财务收据. 留置不计入收款,继续其他审计领域;其作用 仅限待完成的工作。 复合外键还防止生 保留 SQL 从删除未解决的工作。 收货期满前停止复试.

在人口众多的数据库中,迁移需要一个维护窗口:普通 索引构建块成本插入。 或者,在迁移之前,添加无效 和解栏,然后预建六个相同名称/定义的索引 列入清单 `costSettlementStoreMigrationSql` 使用 `CREATE [UNIQUE] INDEX CONCURRENTLY` 在交易之外。 将剩余迁移应用到一个短小的 限制/许可的维护窗口。 此送货执行不 迁移或部署.

JSON 财务扩展名有 DB 密钥/ 形状检查; 呼叫者无法添加即时 或反应领域。 已输入的遗留费用/等级/缓存/警告栏 还有. `turn_id` 无效 : 操作身份是不同的,在 关闭的收据。 DB 检查形状/ 内容表面; 适配器执行值 有效性也一样。 直接的 SQL 收发记录是不支持的 。 读取明显失败 (一) 收条腐败,而不是默默地省略财务数据 这种腐败通过操作员. `list` 过滤器发生、操作、模型 并使用指数进行定价. 这不是一个投影光标:历史晚期定居点仍然清晰可见 `pending`,没有高水位抵消.

## 持久执行日记

`migrateExecutionStore(pool)` 添加 `alma_executions`· ; `PostgresExecutionStore(pool)` 执行 `ExecutionStore` 带有标准的角色/范围/超时选项。 移徙 是添加剂/专有剂,而且赠款选择/插入/更新,绝不删除。 递归 SQL 形状检查甚至排除了价格段和使用情况中的任意内容; 读取时间核心正常化拒绝腐败的价值观。 赠款 `alma_app` 成员 程序登录 `grantRole`,以及其他范围商店.

索赔通过范围化的独特身份序列化。 变异时钟在 行锁; 有界过期扫描使用 SKIP LOCKED. 失去的承诺是 不确定结果, 不允许再次发送: 读取记录或重播 同一不可更改的索赔/证据。 恢复无法进行。 标注 `list` 实值 观察,不是通知传送光标.

现有的会话消除和审计/关闭保留让该刊物无内容 完好无损 在这种迁移中,没有保留期刊或生产回填. 受管跑者使用这个日记. 需要未来的状态扩展 将读者提升到作家之前;老读者拒绝未知状态.

`not_dispatched_cause` 无效, 单独命名的 CHECK 只允许 编号 `not_dispatched` 记录(规格:不分发原因).

## 文档

[文件索引](https://npmcn.com/package/docs/README.md) • 妇女 [变量§1](https://npmcn.com/package/docs/invariants.md) • 妇女 [会话存储 spec](https://npmcn.com/package/docs/specs/001-postgres-session-store.md) • 妇女 [存储光谱](https://npmcn.com/package/docs/specs/011-memory-storage.md)

阿帕奇 - 2.0

### 范围化执行结果(第081项)

运行 `migrateExecutionResultStore(pool)` 移民本金并给予 应用程序登录配置的 RLS 角色 。 构造 `new PostgresExecutionResultStore(pool, { maxSensitivity: "personal", maxRetentionMs: 60000, maxChars: 10000 })`。 。 。 . 两份表格 `alma_result_scopes` 财务报告和审定财务报表 `alma_execution_results` (一) 部队/用户RLS; 该应用程序收到SELECT/INSERT/UPDate,没有DEELETE或全球留存赠款.

每次行动都会锁定精确的瞄准哨,包括第一次准备和空置 范围去除。 读取的锁 因为他们可以 身体过期的内容. 未知读取可能创建范围元数据 。 锁后进行时钟取样; 即使相互冲突的准备被拒绝,也宣告失效. `erase` 清除 待定和可用的行,包括已过期的未过滤内容,但不删除 元数据。 主机时间表已限定 `purgeExpired` 租户/用户的电话 ;墓碑和范围元数据无限期地保留。 移徙或 存储更改财务或执行日记。 已无法取消输入 由主机或提供者读取,主机必须审核其去除构成.

## 持久使用

安装新 `@alma-harness/execution` 端点并运行 `migrateUsageInbox(pool)`。 。 。 . `PostgresUsageInbox(pool, opts?)` 使用标准角色/镜像/超时设置. 日刊 和收件箱移出相同的共享形状验证符,按任一顺序工作. 不可改变 `alma_usage_inbox` 行只允许应用 SELECT/INSERT. 单独范围 待定的表格允许DELETE进行确认,并附有接收时间戳 (原始内容存档于2018-03-27). by FK. 两种表格都迫使 RLS. 在插入和精确重放前只赢 在不恢复已经得到承认的工作的情况下,解决失去的承诺承认问题.

`list` 保留已确认的历史; `listPending` 选择工作。 两者均有界限 独家 `(receivedAt,id)` 页面; 重新启动每张通行证以捕捉迟发承诺 . 一个合乎逻辑的消费者拥有回收和确认。 比较完整的日记 在确认前有约束力并持续恢复/解散;无订阅者 扇出,自动结算或再发送. 届会/成果消除和保留 不删除收件箱元数据。 见 [执行软件包](https://npmcn.com/package/%40alma-harness/execution/README.md)。 。 。 .

## 管理的财政收入

运行 `migrateGovernedCostSettlementStore(pool)` 在使用前 `settleGoverned`, (中文(简体) ), `getGoverned`, (中文(简体) ), `listGoverned` 或者说 `pendingGoverned` 打开 `PostgresCostSettlementStore`。 。 。 . 移民还更新了普通定居计划。 普通升级 和解码需要重运行 `migrateCostSettlementStore` 用于其模式旗. 现有的有效载荷CHECK不变;不可改变的FORCE-RLS扩展仓库 关闭请求/决定元数据。 申请补助金仅为SELECT/INSERT.

一个交易锁定会话然后 Org-day 计数器, 抓取实际的前一个 增加、费用、决定和待决工作。 一个受管 操作/呼叫有一个收据。 跨模式或身份/政策再利用冲突 回滚;回放保留了原作的决定. `capsCrossed` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}还是只发出警告 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你应该知道. 断层证据从不从这家店里扔钱 不唤供养.

普通保留路径会无限期地跳过被控制的成本,即使在它们 将确认预测。 其他符合条件的费用和审计家属仍然到期. 产品消除无法重置这些收据。 使用原发生时间和 绝不向两个会计作者收取费用。 受管跑道和操作会计是单独的包.

管理下的财务连接需要 PostgreSQL 浮式往返输出 (单位:千美元)`extra_float_digits >= 1`,“PostgreSQL 12+”默认值;四舍五入的浮标文本可以 未能进行准确的财务一致性检查。 在角色/集合选项中保留此设置 .

需要管理期刊 **两者** `migrateExecutionStore` 财务报告和审定财务报表 `migrateUsageInbox`。 。 。 . 他们的CHECK将版本的v2形状函数称为". 已解决/完成的元数据得以消除,但历史成功无法恢复 过期的结果内容 。 完成和财务结算仍然分开, 一能收回的交易。 日记从不增加费用本身.

管理下的单次呼叫收养在 通过迁移AuditLog的路径和进入路径. 现有行仍可读 与无相关性。 运行此迁移到其它管理过的商店 使用匹配的单调跑道和审计适配器.

温度控制使用 v2 结构检查, 仅排除投影 新密钥, 加数字 `0..2` 检查。 旧的应用程序读者拒绝,所以 在温度写入器之前部署匹配的读取器( spec: 明文温度控制) .

操作行号在 `@alma-harness/postgres-execution`· ; 它重复了导出的内容 `inScope`, (中文(简体) ), `resolveRlsRole` 财务报告和审定财务报表 `resolveStatementTimeout` 帮助者( spec: 持久操作行).

迁移将 SQL 函数的依赖关系连接到 `pg_catalog, installation_schema, pg_temp` (规格:恢复-安全-sql-函数). 首先选择信任的安装方案 关于迁移连接; 不给那里运行的 CREATE 。 函数权利中止 引用者和 pg dump 保留路径 。 备份前重运行当前迁移; 被冻结的旧起动SQL可以替换定义并去掉这个配置.

重运行执行/ 插件移取已验证的上下文拒绝; 首先部署匹配的读取器( spec: safe-context- rejection- rotation) . 同样的再运行安装了预流拒绝证明,每个都绑定在它的提供者上(光谱:预流-回放). 以后永远不要运行旧释放的迁移:他们恢复一张拒绝这些证明的支票.

## 退休转会协调

新鲜主机使用 Canonial 运行时间而从未创建 `alma_turn_claims` 或者说 `alma_turn_leases`旧建筑商和移民出口被移除。 现有 SQL 数据不被丢弃或重写. 混合部署必须保留历史 清理适配器和 `turnRecords: "claims"` 保持姿势直到其内容消失; 只有没有历史索赔的东道主可以声明 `turnRecords: "none"`。 。 。 . 任何角色成员资格或执行权限都不由清理产生. 财务支出 收据、日记账和审计库存仍为单独留存的表面.

工具选择( spec: 被管理的工具选择): 一个单独的版本的 SQL 帮助检查 在 v2 形状和 拒绝帮助者。 经济、社会、文化权利委员会(CHECK)按移民顺序和移民时间排列 移民又开始流动。 没有可选字段的记录仍然有效。 这个可以 不授予执行权, 更改 RLS 或持续响应内容 日记/收件箱.

## 常见问题

### @alma-harness/postgres 是什么？

Alma的Reference Postgres存储适配器:SessionStore和内存存储器\(episodes, profile,去除水印\),在\{org,uid\}上键入行级安全\.

### 如何安装 @alma-harness/postgres？

在项目目录运行 npm install @alma-harness/postgres，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@alma-harness/core（^0\.41\.0）、@alma-harness/memory（^0\.41\.0）、@alma-harness/execution（^0\.41\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alma-harness/postgres 支持 TypeScript 吗？

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

### @alma-harness/postgres 支持 ESM 还是 CommonJS？

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

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

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

### @alma-harness/postgres 可以商用吗？

@alma-harness/postgres 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @alma-harness/postgres 的下载量有多少？

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

### @alma-harness/postgres 还在维护吗？

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