pgstore

package
v0.47.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 18 Imported by: 0

README

examples/pgstore —— PostgreSQL 参考存储 + 部署案例

sideeffect.Store / sideeffect.FencedSink / taskboard.Board(含 RenewingBoard)/ checkpoint.StoreCAS / controlplane.Store 的 PostgreSQL 参考实现,连同把它们的判据在真实数据库上跑通的集成环境。

它是参考实现,不是内核依赖(「内核不实现存储」的边界不动):内核包的 依赖图里没有 pgx;本子包只属于 examples/,宿主照抄它、不 import 它。 与 examples/reference-runtime(内存版)的分工:内存版证明判据本身是对的, 这一份证明判据在跨进程下依然成立——用内核的共享契约套件 (sidetest / boardtest / sidetest.RunSinkContract)在真实 PostgreSQL 上 原样跑通,不为任何实现开后门(场景级硬失败)。

判据落库形态(宿主抄它的那部分)

契约 落库形态
sideeffect.Store.Acquire 一个事务里的三判合一:SELECT … FOR UPDATE 行锁(锁序恒为资源行 → 动作行)+ 按契约顺序判定(已完成 > 结果未知 > 执行中 > 资源被占 > 授予);授予时令牌 = 已见最大值 + 1、持有者身份 sideeffect.MintHolder() 同事务铸造、执行意图同事务落库
Complete / Release / Abandon / Renew / MarkUncertain 同一事务内三项联查(令牌 + 持有者 + 资源一致),校验失败即整体回滚——「标记写失败必须保住执行意图」由此成立
ResolveUncertain / BeginReconcile 裁决不校验栅栏(依据是下游事实);对账占用同刻至多一人,过期可重入
sideeffect.FencedSink.WriteFenced 一条带条件的 INSERT … ON CONFLICT DO UPDATE … WHERE seen_fence <= presented 原子预占;写入体经 ExecWithin 走同一事务,报错即整体回滚(不得部分写)
taskboard.Board 认领是事务内的读-判-写;令牌随机铸造、接管代次同一次落库;释放/完成/续期条件更新只认令牌
checkpoint.StoreCAS 条件 upsert(WHERE 已持久化序号 < 本次序号),Seq == 0 先拒
租户隔离(issue #275) effect / 资源 / 下游 / 事件表的键均为 (tenant, 业务键) 复合主键;租户作用域实例(NewTenant*)从 ctx 取租户,缺租户 ⇒ tenant.ErrNoContext(写入被拒),声明与 ctx 不一致 ⇒ ErrTenantMismatch;事件每个租户一条独立 ID 空间与水位行,订阅侧按流过滤;尾随游标用 NewTenantTailCursorStore 按 (tenant, consumer) 隔离
controlplane.Store(issue #278) 三个 Snapshot* 在 REPEATABLE READ 只读事务里取一致快照;三个 Commit* 在 pgref_control_version 单行版本锚上「校验 → 留痕 → 写状态 → 推进版本」同事务;任务状态落在 pgref_board_task(与 taskboard 同一张可写表),运行成员由该表 run_id 单源表达。ControlStore/BoardStore 的 TaskSourceID 同 schema 一致,NewAuthoritativeStorePlane 装配期判同源

跑起来(三选一,按场景)

1) 部署冒烟:一条命令起环境(默认 profile)
docker compose -f examples/docker-compose.yml up --abort-on-container-exit --exit-code-from smoke

起 postgres:16 + 参考宿主冒烟(cmd/pgsmoke:幂等键重放 / 栅栏拒陈旧 / 双宿主竞争恰好一个 applied / 双 agent 认领恰好一个赢家),退出码 0 即通过。

2) 契约验证:同一套共享套件 + SIGKILL e2e(verify profile)
docker compose -f examples/docker-compose.yml --profile verify up \
  --abort-on-container-exit --exit-code-from contract

跑 go test ./examples/pgstore/ 的全部内容(见下)。

3) 本地开发(复用宿主 Go 工具链,最快)
make integration        # compose 起 postgres → go test → down;compose 起不来会明确报错
# 或指向已有实例:
GAK_PGREF_DSN=postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable \
  go test ./examples/pgstore/ -count=1

无 PostgreSQL 时用例在环境入口显式跳过(t.Skipf 写明原因与起法, go test -v 可见);套件场景本身不跳——跑不过就是跑不过。

测试都判了什么

层 内容
TestSideEffectStoreContract sidetest 33 条:三判合一 / 三项联查 / 执行意图 / 结果未知 / 对账占用(含带凭据裁决与 TTL 校验)/ 动作身份不可变 / 过期租约拒续期 / Unsafe 裁决 / 标记失败……与内存版参考实现跑同一段套件(issue #94 的核心验收)
TestTaskBoardContract boardtest 全家族(含并发认领 10 与 100 两档)
TestDownstreamSinkContract sidetest.RunSinkContract 6 条:栅栏一族(issue #84 的核心验收,判据收编自 sideeffect 包内用例)
TestSnapshot… 快照单调闸(拒陈旧 / 拒零 / 无记录 NotFound / 并发同序号恰好一个赢家)
TestPGE2E* 真实进程故障恢复(issue #95):子进程执行动作 → SIGKILL → 等 TTL 过期 → 断言同一 Key 转需对账不被重放;对账「已生效」后只重放结果;双进程竞争恰好一个 OutcomeApplied。子进程是 re-exec 本测试二进制(unix build tag),跨进程共享状态只有 PostgreSQL
TestPGE2ETwoProcessSnapshot* 跨进程快照单调(评审第三节场景「两个进程同时提交快照」):两个真实子进程经同一绝对时刻屏障同时提交——同序号恰好一个写入一个被拒,不同序号落库的必然是较大那个(只进不退),且竞争结束后闸依然立着
TestEffectStore*Tenant* / TestEventStore*Tenant* / TestDownstream*Tenant* 租户隔离(issue #275):跨租户同 TaskID 同参数互不重放、同租户不同 Run 互不命中、事件每租户独立 ID 空间与水位线、下游栅栏按 (tenant, resource) 隔离、缺租户 fail-closed、旧库 vN+1 迁移幂等
TestEffectStoreLegacyKeyReplaysAcrossTenants 反向验证(issue #275):去掉租户维度(不拼键、不分区)后第二个租户必然拿到 Replayed——证明修复不是「测了个本来就绿的东西」
TestControlStore* 控制面持久化(issue #278):快照一致 + 版本锚(旧快照提交 ErrStoreConflict,并发只有一个赢家)、缺留痕面/留痕失败状态一字不动、SnapshotRun/CommitRun/效果账、CommitTask 与 Board.List 同表可见、同 schema 同源装配、不同 schema ErrAuthorityMismatch;权威 ForceRelease 后旧令牌完成被同一张任务板拒收

CI 的 integration-pg job(postgres service container)每次推送都真跑同一批用例。

compose 服务清单

服务 profile 职责
postgres 默认 PostgreSQL 16(healthcheck 门控依赖方)
smoke 默认 参考宿主冒烟(cmd/pgsmoke)——「起环境即验证部署可用」
contract verify 共享契约套件 + SIGKILL e2e 在容器里真跑
Kubernetes(可选 profile,非默认路径)

compose 里的三个角色对应 K8s 对象:postgres → StatefulSet(持久卷 + readinessProbe 对应 healthcheck)、smoke/参考宿主 → Deployment(环境变量 GAK_PGREF_DSN 指 Service DNS)、contract → Job(跑同一批契约用例,作为 发布前的验收闸)。本仓不附带 manifest:无云环境时 compose 已覆盖全部可验证 面,K8s 形态留给宿主按自己的底座装配。

新依赖

github.com/jackc/pgx/v5(v5.13.0,纯 Go,CGO_ENABLED=0 交叉构建不受影响)—— 只进本子包的依赖图,内核各包 requires 均不含它(policy 的 dependency_direction.ext_prefixes 登记了 github.com/jackc,内核包若 import 驱动会被依赖方向门禁当场拦下)。

Documentation

Overview

board.go —— taskboard.Board 的 PostgreSQL 参考实现。

判据落库形态

  • **认领是读-判-写不可分割**:一个事务里 SELECT … FOR UPDATE 锁任务行, 依次判(不存在 / 终态 / 依赖 / 被活持有),通过才写——两个进程同时认领 同一任务时,输家会在行锁上等到赢家提交,然后读到 claimed 状态 ⇒ ErrTaken。并发正确性由 taskboard.ConcurrentClaim 的共享套件判。
  • **令牌与接管代次由存储铸造**:令牌用随机 128 位(跨进程不复用不重合, ABA 封死);代次 = 该任务已见最大值 + 1,与令牌同一次写落库(同源)。
  • **释放 / 完成 / 续期只认令牌**:条件更新 WHERE token = $2,影响行数为 0 即 ErrLeaseLost(迟到持有者放不掉别人的闸)。

到期时刻由**存储自己的时钟**算(可注入):调用方的时钟与存储的时钟可能 对不上,跨进程时更不能假设一致。

control.go —— controlplane.Store 的 PostgreSQL 参考实现(issue #278)。

它补的是哪一段

控制面此前只有进程内 MemStore:两个副本各持一份状态,A 的强制释放 / 裁决 / 终止在 B 的视图里不可见(#189)。更危险的是宿主被迫自己写一份 可写的任务表——控制面与 taskboard 各改各的,人工强释只改了一个投影 (#268)。本实现把 Store 落到 PostgreSQL,并**复用 pgref_board_task 作为 唯一的可写任务状态**:

  • 任务快照 / 提交只读写 pgref_board_task(与 taskboard.Board 同一张表);
  • 运行记录 pgref_run 只存 status / gen,任务成员由 task_ id 的 run_id 列单源表达——不复制一份任务清单;
  • 强制释放的权威接线仍是 NewAuthoritativeStorePlane + BoardStore (#268):控制面不绕过任务的令牌 / 代次判据。ControlStore 的 CommitTask 只是 **Store 契约**的后端落点(供非权威装配或测试使用)。

三条硬契约的落库形态

  • **快照一致**:三个 Snapshot* 都在一个 REPEATABLE READ 只读事务里读 版本锚与全部相关行(任务集合不是边改边读的流);
  • **版本锚**:pgref_control_version 单行全局修订号;Commit* 先 SELECT … FOR UPDATE 校验 expect,不符即 ErrStoreConflict 且什么都不写; 提交成功推进修订号;
  • **留痕与状态同事务方向**:Auditor.Append 在版本行锁下、状态写入之前 调用;留痕失败 ⇒ 事务回滚,状态一字不动。宿主 Auditor 若落在另一个 数据库,跨库原子性不成立——这是宿主账本的边界,与 MemStore 同口径 (内核要求的是「留痕失败不得改状态」,不是替宿主实现两阶段提交)。

同源声明(issue #268)

ControlStore 与 BoardStore 都实现 controlplane.TaskSource,来源标识由 pool 的 host/port/database/search_path 派生:同一 schema 的两者返回相同 值,NewAuthoritativeStorePlane 据此在装配期判定「同一张任务表」;不同 schema / 不同库的来源不同 ⇒ ErrAuthorityMismatch。这是不靠类型猜同源的 可机判落点。

control_seed.go —— ControlStore 的装载入口(从 control.go 拆出,只为守住 「单文件 400 行」的结构阈值;判据归属不变)。

cursor.go —— eventbus.Tailer 游标持久化(eventbus.CursorStore)的 PostgreSQL 参考实现(issue #264 的「崩溃点重启续读」)。

为什么需要它

eventbus.Tailer 的游标默认是 Run 的局部状态,停机即失;只有装配 CursorStore 才能从上次停点续随(eventbus.CursorStore 契约:Load 失败停摆、 Save 失败不停摆、未命中回退显式起点 / MaxID)。仓内此前只有测试替身 (eventbus 的 memCursorStore)满足这条接缝,生产宿主接 PostgreSQL 时没有 参考落点——本实现补上这一环。

语义

  • 一行一个消费者(consumer key):同一键的游标只有一条,Load 未命中 = found=false(首次部署);读失败返回 error,Tailer 会停摆重试,绝不 静默回退 MaxID(回退即跳过停机窗口)。
  • **游标单调不减**:SaveCursor 用 GREATEST 吸收回退写(陈旧副本的迟到 保存不会把游标拉回去);非法回退不报错、不落库。
  • 保存是独立 UPSERT,不与事件发布同事务:游标不是业务状态,Tailer 在 投递之后保存——崩溃窗口只会造成重启后重读(订阅侧游标幂等吸收), 不会跳读。
  • 同一 consumer key 只应由一个尾随者写(多副本各用各的键);同键并发写 的语义是「最后落库的最大值获胜」,不承诺无重复投递。

Package pgstore 副作用闸 / 任务认领面 / 进度快照 / 可靠事件面(Outbox 形态)/ 控制面状态存储的 **PostgreSQL 参考实现**。

生命周期: Experimental(v0.33.0 定级)——参考实现,随契约套件与参考部署 演进,不承诺任何兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级 规则见 docs/api-compat.md。

它是什么、不是什么

这是 examples 里的**参考实现**,不是内核依赖:内核(sideeffect / taskboard / checkpoint)依旧只给契约与判据,不给存储。本包演示的是「把同样的判据落到 一个真实数据库的原子操作上」长什么样——宿主照抄它,比照着契约散文重写, 漂移的概率小一个量级。

它与 examples/reference-runtime(内存版参考实现)是一对:

  • 内存版证明「判据本身是对的」(进程内互斥锁即可);
  • 本包证明「判据在**跨进程**下依然成立」(判据归存储,不归进程)—— 用内核的共享契约套件(sidetest / boardtest / RunSinkContract)在 真实 PostgreSQL 上原样跑通,不为任何实现开后门。

三套契约各自的落库形态

  • sideeffect.Store:Acquire 的「三判合一」(已完成 > 结果未知 > 执行中 > 资源被占 > 授予)在一个事务里完成——SELECT … FOR UPDATE 行锁把 「读状态 → 判 → 写」钉成跨进程原子;执行意图与授予(令牌 + 持有者身份, sideeffect.MintHolder 在同一事务里铸造)写在同一事务里。Complete / Renew / MarkUncertain / Abandon / Release 全部三项联查(令牌 + 持有者 + 资源一致),缺一即拒(ErrFenceStale / ErrNotHolder / ErrResourceMismatch)。
  • sideeffect.FencedSink:一条带条件的 INSERT … ON CONFLICT DO UPDATE (WHERE seen_fence <= presented)先原子预占,写入体在同一事务里执行; 写入体报错 ⇒ 整个事务回滚 ⇒ 不得部分写。
  • taskboard.Board:认领是一个事务里的读-判-写(行锁),令牌与接管代次 在同一次操作里铸造;释放 / 完成 / 续期只认令牌。
  • checkpoint.StoreCAS:一条带条件的 upsert(WHERE 持久化序号 < 本次序号), 影响行数为 0 即判陈旧。
  • controlplane.Store(issue #278):三个 Snapshot* 在 REPEATABLE READ 只读事务里取一致快照;三个 Commit* 在 pgref_control_version 单行版本锚 上「校验 → 留痕 → 写状态 → 推进版本」同事务提交(留痕失败 ⇒ 状态一字 不动)。任务状态与 taskboard.Board 共用 pgref_board_task 这**一张可写 表**,运行成员由该表的 run_id 单源表达;ControlStore 与 BoardStore 的 TaskSourceID 同 schema 一致,NewAuthoritativeStorePlane 据此装配期判 同源(issue #268)。权威接线仍走 NewAuthoritativeStorePlane:强释经 任务板令牌/代次判据,裁决经副作用闸同一份状态。
  • eventbus 可靠事件面(Outbox 形态,issue #264):事件行与业务状态同 事务提交(PublishInTx——事件与业务写入同生共死),ID 由每租户一行 水位表串行化铸造(铸造序 == 提交序,回滚不烧号 ⇒ 序列空洞结构性地不存在), 读侧以已提交水位线为上界(TailStore / WatermarkTailStore)。这是 eventbus.TailStore 契约点名的唯一被承诺支持的生产形态;自增直读 (BIGSERIAL + WHERE id > cursor)被该契约显式声明不支持。 尾随游标经 TailCursorStore(pgref_tail_cursor)持久化——实现 eventbus.CursorStore,崩溃/停机后从上次停点续读(#264)。

租户作用域(issue #275)

effect / 资源 / 下游 / 事件四张表都带 tenant 列,键按 (tenant, 业务键) 联合定位:跨租户同名任务与同 Key 动作互不命中。装配期两种形态:

  • 默认(NewEffectStore / NewEventStore / NewDownstream):旧布局, tenant 取动作 / 事件自带值(空 = ”);单租户部署逐字不变。
  • 租户作用域(NewTenantEffectStore / NewTenantEventStore / NewTenantDownstream):每次调用从 ctx 取租户(tenant.Require), 缺租户 ⇒ tenant.ErrNoContext(写入被拒,fail-closed);声明与 ctx 不一致 ⇒ ErrTenantMismatch。

事件面每个租户一条独立 ID 空间与水位行(pgref_event_watermark 主键 tenant):订阅侧用租户作用域实例取流即按租户过滤,单租户流仍满足 TailStore 的「无空洞推进」——过滤共享 ID 空间会产生永久空洞。 尾随游标经 NewTenantTailCursorStore 按 (tenant, consumer) 隔离(同一 consumer 名在两个租户下是两条游标,跨租户不会互相推进)。 旧库由 EnsureSchema 的 vN+1 迁移补齐租户列 / 复合主键(旧行归入 ”)。

时钟

过期判定的时间源(v0.33.0 后修正):**缺省读数据库的 clock_timestamp** (事务内、取得行锁之后),经 UseClock 可注入(sidetest / boardtest 的 硬要求:注入值是系统时间的测试替身)。

为什么不再是进程本地的 time.Now:租约与执行意图是**跨节点共享的事实**, 各 worker 用自己的时钟写入/判定到期时刻时,±10s 的时钟漂移对 15s 的 TTL 意味着「A 写入的租约在 B 看来从一开始就是过期的」⇒ B 提前接管 A 仍在执行的资源。数据库只有一个时钟,判定读它,漂移就没有入口。 取时刻必须在**取得行锁之后**:CURRENT_TIMESTAMP 固定在事务开始时刻, 事务在锁上等了几秒的话,用它判过期会把等锁时长算进租约寿命。

数据库连接

构造函数直接收 *pgxpool.Pool 与 schema 名:本包不管理连接串与凭据, 那是宿主的接线责任。隔离方案是**每个实例一个 schema**(EnsureSchema 建 CREATE TABLE IF NOT EXISTS 一套表),契约套件每个子测试建一份全新实现 ——与「factory 每次构造全新实现」的套件约定对齐。

部署与验证入口

  • 契约 + 故障恢复用例:GAK_PGREF_DSN=… go test ./examples/pgstore/… (见 examples/docker-compose.yml 与 Makefile 的 integration 目标);
  • 冒烟部署:docker compose -f examples/docker-compose.yml up(pgsmoke 服务)。

effect.go —— sideeffect.Store 的 PostgreSQL 参考实现:类型、事务骨架与行读写。

三条判据在库里的落法(与内存版 effectStore 逐条对应)

  1. **三项联查**:Complete / Release / Abandon / Renew / MarkUncertain 都在 同一个事务里校验「令牌仍是最新代 + 持有者身份一致 + 租约与动作的资源 一致」。校验与写入在同一事务 ⇒ 任何一步失败都发生在**任何状态被改之前** ——这正是 MarkUncertain「标记写失败必须保住执行意图」的落库形态。
  2. **执行意图**:Acquire 的授予(令牌 + 持有者身份)与意图登记写在 同一事务里;意图过期未裁决 ⇒ 同一 Key 转入未知态而非重新授予。
  3. **对账占用**:BeginReconcile 与裁决分表字段,占用过期可重入。

原子性来自哪里

每个方法 = 一个事务 = 若干条 `SELECT … FOR UPDATE` + 条件写。行锁把 「读状态 → 判 → 写」钉成跨进程原子:第二个进程在第一个提交前读到的 永远是旧状态,且会在行锁上等待。这与「一条带条件的 UPDATE」等价, 是契约点名认可的两种形态之一。

锁序恒为「资源行 → 动作行」:所有方法按同一顺序加锁,两个并发事务 不可能交叉持锁(交叉死锁在锁序一致时不存在)。

effect_acquire.go —— Acquire:三判合一的一个事务。

判定顺序是契约里最要紧的一行:**已完成 > 结果未知 > 执行中 > 资源被占 > 授予**。 顺序写反的代价是重复施加:把「结果未知」排到「资源被占」之后,调用方会拿到 contended(以为「晚点重试就行」),于是重试发生、重复施加随之发生。

为什么整段在一个事务里:三判合一的每一步都读同一份状态,行锁保证第二个 进程要么读到判定前的旧状态(然后在锁上等),要么读到判定后的新状态—— 不存在「两个进程同时读到没做过、资源空闲」的窗口。

effect_lease.go —— 凭据一族:Complete / Release / Abandon / Renew / MarkUncertain。

五个方法共用同一套纪律:

  • 校验与写入在**同一个事务**里 ⇒ 校验失败即整体回滚,存储侧不剩半截状态;
  • 资源行 → 动作行的固定锁序(见 effect.go);
  • 三项联查不过即拒(ErrFenceStale / ErrNotHolder / ErrResourceMismatch), 拒绝时**不落任何一行**。

effect_reconcile.go —— 对账侧:ResolveUncertain 与 BeginReconcile。

裁决**不校验栅栏**(契约硬要求):它的依据是**下游事实**,不是持有权—— 原持有者可能已经死亡、租约早已过期,而对账恰恰要在这种情况下进行。 占用与裁决的关系:占用过期可重入(对账者死亡不永久占住);裁决成功即 清除占用(这次尝试已有结论)。

effect_rows.go —— effect 存储的行级读写与凭据联查(从 effect.go 拆出, 只为守住「单文件 400 行」的结构阈值;判据归属不变)。

event.go —— eventbus 可靠事件面(Outbox 形态)的 PostgreSQL 参考实现。

形态声明(与 eventbus.TailStore 的契约文字一致,issue #264)

eventbus 的尾随读侧契约把「无空洞推进」收口为:**被承诺支持的生产形态 只有 Outbox**。本实现就是那个形态的落库样板:

  • **写侧(事件行与业务状态同事务)**:PublishInTx 在调用方事务内落 事件行;业务写入与它共用同一个事务——提交则同现,回滚则同灭。
  • **分配串行化(水位行)**:ID 由单行水位表 pgref_event_watermark 铸造 ——UPDATE … RETURNING 拿号的同时持行锁到事务提交,下一个发布者在 锁上等待 ⇒ **铸造序 == 提交序**,乱序提交结构性地不存在(issue #264 实证的丢帧序列「小 ID 在途、大 ID 先提交」在此形态下无法发生)。
  • **回滚不烧号**:拿号、插行、业务写入全在同一事务,回滚一并消失 ⇒ 序列空洞结构性地不存在(对比 BIGSERIAL:回滚烧号 ⇒ 永久空洞, 水位线读法将在那里永久停摆)。
  • **读侧(已提交水位线读法)**:ListAfter 的返回段以水位线为上界 (id > cursor AND id ≤ 水位线)——水位线之上哪怕已可见也扣住不返 (fail-closed 方向是扣住,不是放行)。无空洞推进由机制保证,不靠 观测截断。

明确不支持:用 BIGSERIAL + WHERE id > cursor 直读实现本面——那是 eventbus.TailStore 契约点名的违约形态(哨兵响但帧已永久丢失;回滚烧号 造成永久停摆)。宿主接自己的自增表时,先读契约再决定,不要抄这个面 之外的捷径。

与 DurablePublisher 的分工

与业务状态无原子性要求的事件仍走 eventbus.DurablePublisher + 本实现的 Insert(独立事务形态,满足 eventbus.Store);要求「事件与业务状态同生 共死」的发布走 PublishInTx——宿主在自己的业务事务里调它,**提交之后** 再广播(广播在事务外,回滚后的幻影帧由此排除)。两入口落同一张表、同一 套水位线,读侧(Tailer)无差别。

串行化的代价(写明,不藏)

全部事件发布在水位行锁上串行——与 DurablePublisher 持锁串行 Insert 同款 取舍(事件是人的可读留痕而非高频指标,不是高频指标的形态)。水位行锁持 有到事务提交:业务事务较长时把 PublishInTx 放在事务末段,别让「拿号」 挡住其他副本的发布。

schema.go —— 连接池构造与建表。

表结构与判据的对应关系(每张表管一件事,见 doc.go):

  • pgref_effect_action Key 级状态(做过没有 / 结果未知 / 执行意图 / 对账占用)
  • pgref_effect_resource 资源级状态(这个资源谁占着 / 发第几代令牌)
  • pgref_downstream 下游资源(已见最大令牌 + 参考业务数据,FencedSink 的落点)
  • pgref_board_task 任务认领面(taskboard.Board)
  • pgref_snapshot 进度快照(checkpoint.StoreCAS)
  • pgref_event_watermark 已提交水位线(**每租户一行**;事件 ID 分配的串行化点,#264/#275)
  • pgref_event 事件行(与业务状态同事务提交的落点,#264;含租户列 #275)
  • pgref_tail_cursor 尾随游标持久化(eventbus.CursorStore,#264 重启续读)
  • pgref_run 运行状态(控制面 Store 的落点,#278;任务成员由 pgref_board_task.run_id 单源表达,不另存一份可写任务状态)
  • pgref_control_version 控制面版本锚(单行全局修订号,#278)
  • pgref_control_effect 控制面效果裁决账(#278;权威接线优先用副作用闸)

sink.go —— sideeffect.FencedSink 的 PostgreSQL 参考实现(下游栅栏适配)。

原子性要求(实现这条契约的唯一要点)

「比较与写入必须在**同一次原子操作**里完成」——本实现把它落成两件事:

  1. **栅栏预占是一条带条件的 upsert**:INSERT … ON CONFLICT (resource) DO UPDATE SET seen_fence = EXCLUDED.seen_fence WHERE seen_fence <= presented。 影响行数为 0 ⇒ 令牌陈旧(ErrFenceStale),此刻**什么都没写**; 影响行数为 1 ⇒ 预占成功,且这行就是「比较 + 更新已见最大」本身。
  2. **写入体在同一事务里执行**:ctx 里带上了事务句柄(TxFromContext), 写入体的业务写入必须用 ExecWithin / QueryRowWithin 走这个事务。 写入体报错 ⇒ 整个事务回滚 ⇒ 预占与已写的业务数据一起消失—— **不得部分写**。

反面教材(为什么不能三步写)

「先读已见最大 → 判断 → 再写入」三步各自独立提交时,两个持有者可以同时 读到同一个旧值、双双通过检查,然后先后写入——更旧的那次写入反而后落, 覆盖掉更新的。栅栏形同虚设。这条失败形态在 sideeffect 包内有确定性用例 (TestNonAtomicSinkIsCaught)与共享套件的并发场景双向钉住。

snapshot.go —— checkpoint.StoreCAS 的 PostgreSQL 参考实现。

契约只有两条,落库形态也是两条:

  • SaveIfNewer:一条带条件的 upsert(WHERE 已持久化序号 < 本次序号), 影响行数为 0 ⇒ 判陈旧(ErrStaleSeq),**不写入**;Seq == 0 一律先拒 (它不是一次真实提交,放它落库等于给了它唯一能覆盖既有快照的写)。 并发提交同一 run 时,两个进程的条件更新在行锁上排队,只有序号更大的 那个落库——单调闸在存储侧成立,不在进程侧。
  • Load:无记录返回 ErrNotFound(**不得**返回零值 + nil——那会被上游 误判成「这个运行从没跑过」从而全量重跑)。

tenant.go —— 租户作用域的装配期声明与解析(issue #275)。

两种形态,一个判据入口

  • **默认(旧布局)**:构造器 NewEffectStore / NewEventStore / NewDownstream 不声明租户作用域,租户列取动作 / 事件自带的 Tenant(空 = ”)。既有 单租户部署逐字不变;宿主显式给了 Action.Tenant / Event.Tenant 时, 存储仍按该值分区(不会静默并进 ” 流)。
  • **租户作用域**:NewTenantEffectStore / NewTenantEventStore / NewTenantDownstream 在装配期声明(与 coord.NewTenantBoardAdapter 同款)。此后每次调用都从 ctx 取租户:缺租户 ⇒ tenant.ErrNoContext (fail-closed,**不是**「不限」);动作 / 事件自带的 Tenant 若与 ctx 不一致 ⇒ ErrTenantMismatch(同一份写入不能有两个租户结论)。

解析只发生在**入口**:公共方法先把作用域解析成具体租户,再交给 SQL。 下游 SQL 一律 (tenant, 业务键) 联合定位,不存在「先按键查、再补租户 过滤」的两步窗口。

Index

Constants

This section is empty.

Variables

View Source
var ErrIntentIncomplete = errors.New("pgstore: 执行意图列部分填充,拒绝判定")

ErrIntentIncomplete 动作行的执行意图四列**部分填充**(半写行)。

这是存储侧数据损坏 / 仓外写入方只写部分列的形态,不是本包写入路径能 产生的状态(本包只写「四列全有」或「四列全空」)。判定遇到它必须 **fail-closed**:逐列解引用会 panic(库层 panic 直接杀宿主进程), 按「无意图」放行会重新授予执行权(重复施加的入口重新打开)。

View Source
var ErrTenantMismatch = errors.New("pgstore: 声明的租户与上下文租户不一致")

ErrTenantMismatch 声明的租户与上下文租户不一致(同一次操作两个租户结论)。

处置:修声明。调用方要么让 Action.Tenant / Event.Tenant 与 tenant.Context.Tenant 一致,要么不要同时给两份;存储拒绝猜测哪一份是 对的——猜错的方向是跨租户串数据。

Functions

func DropSchema

func DropSchema(ctx context.Context, pool *pgxpool.Pool, schema string) error

DropSchema 删除一个 schema(含其中的表)。

func EnsureSchema

func EnsureSchema(ctx context.Context, pool *pgxpool.Pool, schema string) error

EnsureSchema 在 schema 里建好全部参考表(幂等,可重复执行)。

schema 由调用方先建好(或用 NewSchema 一并创建);本函数只建表。 search_path 用 SET LOCAL 在本事务内指定——否则 DDL 落到调用方连接的 缺省 schema(public)里,读侧的 search_path 指到的却是一套空 schema。

func ExecWithin

func ExecWithin(ctx context.Context, sql string, args ...any) (int64, error)

ExecWithin 在写入体所在的事务里执行一条写入。

不在事务里(ctx 没带事务句柄)时显式报错:静默落到事务外等于绕开栅栏。

func NewSchema

func NewSchema(ctx context.Context, pool *pgxpool.Pool) (string, error)

NewSchema 建一个随机命名的 schema,返回名字。

契约套件的 factory 每个子测试调一次,构造一份**全新**实现——在共享的 数据库里,「全新」的落法是独立 schema:表状态互不可见,t.Cleanup 时整块删除。

func TxFromContext

func TxFromContext(ctx context.Context) (pgx.Tx, bool)

TxFromContext 返回写入体所在的事务句柄。

写入体**必须**通过它(或 ExecWithin / QueryRowWithin)执行业务写入—— 绕开事务自己开连接写入的数据不受栅栏保护,也无法在失败时一起回滚。

func WithTx

func WithTx(ctx context.Context, tx pgx.Tx) context.Context

WithTx 把事务句柄放进 ctx(Downstream 内部用;写入体拿到的是它的产物)。

Types

type BoardStore

type BoardStore struct {
	// contains filtered or unexported fields
}

BoardStore taskboard.Board(含 RenewingBoard)的 PostgreSQL 参考实现。

func NewBoardStore

func NewBoardStore(pool *pgxpool.Pool) *BoardStore

NewBoardStore 构造任务认领面存储。

func (*BoardStore) Claim

Claim 认领一个任务(读-判-写不可分割:一个事务完成)。

func (*BoardStore) Complete

func (b *BoardStore) Complete(ctx context.Context, id taskboard.TaskID, token string) error

Complete 标记完成(凭令牌):终态不带 owner,避免「谁做完的」与「谁还占着」混在一起。

func (*BoardStore) List

func (b *BoardStore) List(ctx context.Context) ([]taskboard.Task, error)

List 返回一致快照(单个事务内读完全部行)。

func (*BoardStore) Release

func (b *BoardStore) Release(ctx context.Context, id taskboard.TaskID, token string) error

Release 归还认领(凭令牌):非持有者释放一律被拒,不许静默成功。

func (*BoardStore) Renew

Renew 续期并确认持有资格(taskboard.RenewingBoard)。

校验(令牌是当前租约的 + 租约未过期)与延长在**同一个事务**里——原子; TTL 语义与 Claim 一致;续期不换令牌、不递增代次(续期不是接管)。

func (*BoardStore) Seed

func (b *BoardStore) Seed(tasks ...taskboard.Task)

Seed 摆初始任务(契约里没有「创建」入口:任务拓扑是宿主的资产)。

签名与套件要求的形态一致(boardtest 经 interface{ Seed(tasks ...Task) } 取用,没有 error 返回位)。落库失败时**panic**:这是装载入口,静默失败 会让套件在一张空表上跑出误导性的结论——摆不进去就当场响。

幂等:同 id 重摆覆盖内容并清租约(套件每个子测试从全新 schema 起步, 生产宿主通常只在装载拓扑时调用它)。

func (*BoardStore) TaskSourceID added in v0.43.0

func (b *BoardStore) TaskSourceID() string

TaskSourceID 实现 controlplane.TaskSource:同一 schema 的 BoardStore 与 ControlStore 报同一来源;不同 schema / 不同库报不同来源(装配期拒绝)。

func (*BoardStore) UseClock

func (b *BoardStore) UseClock(now func() time.Time)

UseClock 注入时钟(boardtest 契约套件用)。

type ControlStore added in v0.43.0

type ControlStore struct {
	// contains filtered or unexported fields
}

ControlStore controlplane.Store 的 PostgreSQL 参考实现。

一个实例绑定一个 schema;并发安全(提交在 pgref_control_version 行锁上 串行化)。aud 为 nil 时所有 Commit* 返回 controlplane.ErrNoAuditor (留痕面缺位 ⇒ 介入一律拒绝,与 MemStore 同口径)。

func NewControlStore added in v0.43.0

func NewControlStore(pool *pgxpool.Pool, aud controlplane.Auditor) *ControlStore

NewControlStore 构造控制面持久化存储。aud 由宿主注入(可为 nil,但那样 只能读不能提交);pool 归调用方管理。

func (*ControlStore) CommitEffect added in v0.43.0

CommitEffect 实现 controlplane.Store:原子提交裁决账 + 留痕。

func (*ControlStore) CommitRun added in v0.43.0

CommitRun 实现 controlplane.Store:原子提交运行状态/代次 + 留痕。

TaskIDs 非 nil 时同步任务归属(run_id),成员只在这张任务表上表达; pgref_run 不存任务清单。nil = 保持原集合不变。

func (*ControlStore) CommitTask added in v0.43.0

func (c *ControlStore) CommitTask(ctx context.Context, expect controlplane.Version, next taskboard.Task, entry controlplane.AuditEntry) error

CommitTask 实现 controlplane.Store:原子提交任务状态 + 留痕。

状态写在 pgref_board_task(与 taskboard.Board **同一张可写表**); 不存在的任务 ⇒ ErrNotFound 且不推进版本。

func (*ControlStore) SeedEffect added in v0.43.0

func (c *ControlStore) SeedEffect(ctx context.Context, key string, st controlplane.EffectState) error

SeedEffect 摆一条效果裁决账(SnapshotEffect / CommitEffect 的装载入口)。

func (*ControlStore) SeedRun added in v0.43.0

func (c *ControlStore) SeedRun(ctx context.Context, id controlplane.RunID, status string, gen uint64, tasks ...taskboard.Task) error

SeedRun 摆一条运行记录与它的任务(参考实现的装载入口,契约里没有 「创建运行」——拓扑是宿主资产)。

任务行落在 pgref_board_task(**与 BoardStore 同一张表**),run_id 建立 归属。同 id 重摆覆盖内容(测试每个子测试从全新 schema 起步)。

func (*ControlStore) SnapshotEffect added in v0.43.0

func (c *ControlStore) SnapshotEffect(ctx context.Context, key string) (controlplane.EffectSnapshot, error)

SnapshotEffect 实现 controlplane.Store:效果键裁决账(同一只读事务)。

func (*ControlStore) SnapshotRun added in v0.43.0

SnapshotRun 实现 controlplane.Store:运行 + 全部任务(同一只读事务)。

func (*ControlStore) SnapshotTask added in v0.43.0

SnapshotTask 实现 controlplane.Store:任务 + 所属 run 的全部任务(同一 只读事务内取,快照一致)。

func (*ControlStore) TaskSourceID added in v0.43.0

func (c *ControlStore) TaskSourceID() string

TaskSourceID 实现 controlplane.TaskSource(见 poolSourceID)。

type Downstream

type Downstream struct {
	// contains filtered or unexported fields
}

Downstream FencedSink 的 PostgreSQL 参考实现。

func NewDownstream

func NewDownstream(pool *pgxpool.Pool) *Downstream

NewDownstream 构造下游栅栏(pool 归调用方管理)。

func NewTenantDownstream added in v0.43.0

func NewTenantDownstream(pool *pgxpool.Pool) *Downstream

NewTenantDownstream 构造**租户作用域**的下游栅栏(issue #275)。

写入 / 读取都从 ctx 取租户;缺租户 ⇒ tenant.ErrNoContext。同一 resource 字符串在两个租户下是两条独立的已见令牌记录——跨租户不会互相抬栅栏。

func (*Downstream) Marker

func (d *Downstream) Marker(ctx context.Context, resource string) (string, error)

Marker 读已落盘的参考业务标记。

func (*Downstream) SeenFence

func (d *Downstream) SeenFence(ctx context.Context, resource string) (sideeffect.Fence, error)

SeenFence 读资源已见过的最大令牌(无记录返回 0)。

func (*Downstream) TenantScoped added in v0.43.0

func (d *Downstream) TenantScoped() bool

TenantScoped 报告本实例是否声明了租户作用域(装配期自检用)。

func (*Downstream) WriteFenced

func (d *Downstream) WriteFenced(ctx context.Context, resource string, presented sideeffect.Fence, write func(ctx context.Context) error) error

WriteFenced 在资源上执行一次带栅栏令牌的写入。

语义(契约逐条对应):

  1. presented 小于已见最大 → 不执行写入,返回 ErrFenceStale(此刻零写入);
  2. 否则执行写入体,并把已见最大更新为 presented(**等于**也放行—— 同一代持有者的多次写入合法,如分批提交);
  3. 第 1 条的判定与第 2 条的写入(含令牌更新)在同一个事务里。

func (*Downstream) WriteMarker

func (d *Downstream) WriteMarker(ctx context.Context, resource string) error

WriteMarker 在写入体里写一个参考业务标记(值追加 'm')。

它是参考实现的「业务写入」占位:宿主的真实业务写入走同一条路 (ExecWithin,同一事务)。供共享套件判「不得部分写」。

type EffectStore

type EffectStore struct {
	// contains filtered or unexported fields
}

EffectStore sideeffect.Store 的 PostgreSQL 参考实现。

一个实例绑定一个 schema(全部表在其中);并发安全。

func NewEffectStore

func NewEffectStore(pool *pgxpool.Pool) *EffectStore

NewEffectStore 构造副作用闸存储。pool 归调用方管理(Close 由它负责)。

schema 必须已建好表(EnsureSchema);search_path 已被连接池指到该 schema (见 NewEffectStores),故本包的 SQL 不写 schema 前缀。

func NewTenantEffectStore added in v0.43.0

func NewTenantEffectStore(pool *pgxpool.Pool) *EffectStore

NewTenantEffectStore 构造**租户作用域**的副作用闸存储(issue #275)。

与 coord.NewTenantBoardAdapter 同款装配期声明:所有方法从 ctx 取租户 (tenant.Require),缺租户 ⇒ tenant.ErrNoContext,写入被拒;Action.Tenant 可与 ctx 一致(推荐显式带上,便于排障),不一致 ⇒ ErrTenantMismatch。

存储键是 (tenant, key) / (tenant, resource):跨租户同 Key 互不命中。

func (*EffectStore) Abandon

func (s *EffectStore) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, _ string) error

Abandon 显式放弃本次尝试:撤销执行意图,并释放(仍是自己的)资源持有。

资源闸只在仍是自己的时才放——易主了就不碰(那是新持有者的闸)。

func (*EffectStore) Acquire

Acquire 一次原子判定(契约语义逐条对照 sideeffect.Store 的文档)。

授予时在同一事务里做三件事:令牌 = 资源已见最大值 + 1;持有者身份由 sideeffect.MintHolder() 在**同一事务**里铸造;执行意图(本次令牌 + 到期 时刻)随授予一并落库。三者分开写就等于没写:中间死掉 ⇒ 意图悬空或没写, 重复施加的入口重新打开。

func (*EffectStore) BeginReconcile

func (s *EffectStore) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)

BeginReconcile 认领对账权:同一 Key 同一时刻至多一个对账者。

仅当该 Key 处于未知态时接受认领;占用未过期时拒绝(ErrReconcileTaken); 占用过期可重新认领(可重入)——对账者死亡不永久占住这个 Key。

func (*EffectStore) Complete

Complete 标记该键的动作已完成并留存结果。**先到者为准**。

幂等:同一 Key 重复 Complete 不报错,返回首次记录的结果(后到者不覆盖)。

func (*EffectStore) MarkUncertain

func (s *EffectStore) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, reason string) error

MarkUncertain 把该键标记为「结果未知」(按键,与资源租约无关)。

标记写失败必须保住执行意图(契约硬要求第 5 条)

本实现「校验 → 改状态」在一个事务里完成:任何一步失败都发生在**任何状态 被改之前**,整体回滚 ⇒ 意图原样留在存储里,后续 Acquire 被意图挡住。 这不是实现自由:落到数据库上时,标记与撤销意图**不得**「先撤意图、再标 未知」分两步提交——第二步失败,存储侧就什么都不剩,另一个 worker 直接重放。

标记成功后意图一并撤销(这次尝试已有结论:未知),但**闸不自动释放** ——调用方还要显式调 Release 只放资源。

func (*EffectStore) Release

func (s *EffectStore) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error

Release 释放**资源持有**,**不动**该键的执行意图。

意图没被裁决之前,这个键不得再被执行——否则「施加成功但进程死在记账 之前」会被下一次 Acquire 变成重复施加。两条出口(Abandon / Release) 不可互相替代,见 Store.Release 的契约注释。

func (*EffectStore) Renew

Renew 续期并**同时确认持有资格**:闸已易主、尝试已失效**或租约已过期** 则拒绝续期(假续期是重复施加的入口)。

func (*EffectStore) ResolveUncertain

ResolveUncertain 裁决「结果未知」的键。**先到者为准**(简化入口, 不校验对账凭据——短对账无须认领,见 OwnedResolveStore)。

RetrySafetyUnsafe 的动作:未生效的裁决不解除阻塞(ErrUnsafeNotRetryable), 必须 Resolution.ForceRetryable 的显式决策才放行——「不可重试」是判据, 不是注释。

func (*EffectStore) ResolveUncertainOwned added in v0.35.0

func (s *EffectStore) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, holder string) (sideeffect.Outcome, sideeffect.Result, error)

ResolveUncertainOwned 带对账占用凭据的裁决(OwnedResolveStore): holder 不是**当前有效**对账认领的持有者 → ErrReconcileLost,不改状态。

校验与裁决同一事务:占用状态被并发接管时,行锁让校验读到的就是裁决 要落的那份状态——「校验时还有效、裁决前已被接管」的窗口不存在。

func (*EffectStore) TenantScoped added in v0.43.0

func (s *EffectStore) TenantScoped() bool

TenantScoped 报告本实例是否声明了租户作用域(装配期自检用)。

func (*EffectStore) UseClock

func (s *EffectStore) UseClock(now func() time.Time)

UseClock 注入时钟(sidetest 契约套件用)。

过期判定必须读它,否则过期场景恒不触发(套件的硬要求)。 注入值代表**系统时间**的测试替身(整个判定链的唯一时间源),不是 「某个 worker 的本地时钟」——修复后的实现里 worker 根本不提供时间, 这正是「租约统一数据库时钟」要达成的状态。

type EventStore added in v0.42.0

type EventStore struct {
	// contains filtered or unexported fields
}

EventStore eventbus 可靠事件面(Outbox 形态)的 PostgreSQL 参考实现: 写侧 PublishInTx / Insert(eventbus.Store),读侧 MaxID / ListAfter (eventbus.TailStore)与 CommittedWatermark(eventbus.WatermarkTailStore)。

一个实例绑定一个 schema(表由 EnsureSchema 建,水位行由建表语句种子化); 并发安全(发布在水位行锁上串行,见文件头「串行化的代价」)。

func NewEventStore added in v0.42.0

func NewEventStore(pool *pgxpool.Pool) *EventStore

NewEventStore 构造事件面存储。pool 归调用方管理(Close 由它负责)。

默认形态 = 旧布局 / 单租户命名空间(tenant ”);事件行仍按 Event.Tenant 落租户列,但读取面固定读 ” 流。多租户部署用 NewTenantEventStore。

func NewTenantEventStore added in v0.43.0

func NewTenantEventStore(pool *pgxpool.Pool) *EventStore

NewTenantEventStore 构造**租户作用域**的事件面存储(issue #275)。

与 EffectStore 同款:所有写读从 ctx 取租户(tenant.Require),缺租户 fail-closed;Event.Tenant 与 ctx 不一致 ⇒ ErrTenantMismatch。每个租户有 自己的水位行与 ID 空间(1..committed),因此租户流仍满足 TailStore 的 「无空洞推进」——过滤共享 ID 空间会产生永久空洞,不能这么实现。

func (*EventStore) CommittedWatermark added in v0.42.0

func (s *EventStore) CommittedWatermark(ctx context.Context) (uint64, error)

CommittedWatermark 已提交水位线读法(eventbus.WatermarkTailStore,#264 的实现声明面):实现本方法 = 声明本存储是 Outbox 形态,可机判口径见 eventbus 包的接口文档。

func (*EventStore) Insert added in v0.42.0

func (s *EventStore) Insert(ctx context.Context, ev eventbus.Event) (uint64, error)

Insert eventbus.Store 的独立事务形态(与业务状态无原子性要求的事件): 内部自开事务,失败整体回滚。DurablePublisher 可直接接本方法。

func (*EventStore) ListAfter added in v0.42.0

func (s *EventStore) ListAfter(ctx context.Context, cursor uint64, limit int) ([]eventbus.Event, error)

ListAfter 列出 id > cursor 的事件(eventbus.TailStore,升序,limit 为单拍 上限;limit 由 Tailer 保证为正——DefaultTailLimit / WithTailBatchLimit)。

返回段被已提交水位线封顶:水位线之上的行哪怕已提交可见(宿主绕过写入 协议落的行)也扣住不返,下一拍水位线推进后再读——fail-closed 方向是扣住 (#264 可机判口径第二条)。水位线机制保证 (cursor, 水位线] 内连续无洞: 水位线只在「对应事件行提交」的那笔事务里推进(同生共死),故对任何可见 快照,≤ 水位线的行全部已提交。读失败不得返回部分结果(契约第四条): 行扫描中途出错即整体作废。

func (*EventStore) MaxID added in v0.42.0

func (s *EventStore) MaxID(ctx context.Context) (uint64, error)

MaxID 当前权威游标空间的**无空洞边界**(eventbus.TailStore,空表 = 0)。

不回裸 max(id):水位线之上的行(宿主绕过写入协议落的行)不得把初始化 游标推过无空洞边界——否则初始化本身就把在途小 ID 跳过(#264)。Outbox 形态下无空洞边界就是已提交水位线(与 CommittedWatermark 同值同源)。

func (*EventStore) PublishInTx added in v0.42.0

func (s *EventStore) PublishInTx(ctx context.Context, tx pgx.Tx, ev eventbus.Event) (uint64, error)

PublishInTx 在调用方事务内发布一条事件(Outbox 形态的写侧入口,#264)。

事件行与调用方在同一事务里的业务写入**同生共死**:提交则同现、回滚则 同灭(水位线推进一并回退,ID 不烧号——下一次发布复用同一 ID)。返回的 权威游标 ID 供提交后的广播携带(提交之后再广播,广播在事务外)。

输入事件的 ev.ID 一律忽略(游标由水位行铸造);Level / Payload 的零值 归一与 DurablePublisher 同口径(见 normalizeEvent);OccurredAt 零值由 数据库时钟补齐(本包时间源纪律,见 doc.go「时钟」段)。

func (*EventStore) TenantScoped added in v0.43.0

func (s *EventStore) TenantScoped() bool

TenantScoped 报告本实例是否声明了租户作用域(装配期自检用)。

type SnapStore

type SnapStore struct {
	// contains filtered or unexported fields
}

SnapStore checkpoint.StoreCAS 的 PostgreSQL 参考实现。

func NewSnapStore

func NewSnapStore(pool *pgxpool.Pool) *SnapStore

NewSnapStore 构造进度快照存储。

func (*SnapStore) Load

func (s *SnapStore) Load(ctx context.Context, runID string) (checkpoint.Snapshot, error)

Load 读取快照。无记录返回 checkpoint.ErrNotFound,不得返回零值 + nil。

func (*SnapStore) SaveIfNewer

func (s *SnapStore) SaveIfNewer(ctx context.Context, snap checkpoint.Snapshot) error

SaveIfNewer 仅当已持久化的序号**严格小于**本次序号时才写入。

type TailCursorStore added in v0.42.0

type TailCursorStore struct {
	// contains filtered or unexported fields
}

TailCursorStore eventbus.CursorStore 的 PostgreSQL 实现:绑定一个 consumer key(如「副本名 / 消费组名」),游标落在 pgref_tail_cursor。

func NewTailCursorStore added in v0.42.0

func NewTailCursorStore(pool *pgxpool.Pool, consumer string) *TailCursorStore

NewTailCursorStore 构造游标存储。pool 不得为 nil,consumer 不得为空—— 两者都是装配期编程错误,fail fast 在构造点(与 eventbus.NewTailer 同口径)。

func (*TailCursorStore) LoadCursor added in v0.42.0

func (s *TailCursorStore) LoadCursor(ctx context.Context) (uint64, bool, error)

LoadCursor 读上次保存的游标(0, false, nil = 从未存过;error = 读失败, Tailer 会停摆重试,不得静默回退 MaxID)。

func (*TailCursorStore) SaveCursor added in v0.42.0

func (s *TailCursorStore) SaveCursor(ctx context.Context, cursor uint64) error

SaveCursor 保存游标(UPSERT;单调不减:回退写被 GREATEST 吸收,不落库)。

失败返回 error,调用方(Tailer)只 warn 不停摆——游标落后只会导致重启后 重读(订阅侧幂等吸收),方向安全。

type TenantTailCursorStore added in v0.43.0

type TenantTailCursorStore struct {
	// contains filtered or unexported fields
}

TenantTailCursorStore **租户作用域**的 eventbus.CursorStore(issue #275)。

为什么需要它:游标是「某个租户事件流」的续读点。多租户部署若两个租户的 尾随者共用一条 consumer key,后跑的会把游标推过对方整段窗口——事件流本身 已按租户隔离(NewTenantEventStore),游标却串了,订阅侧静默漏帧。

装配期声明租户作用域:每次读写都从 ctx 取租户(tenant.Require,缺租户 ⇒ tenant.ErrNoContext)。物理行仍是 pgref_tail_cursor,consumer 键由 tenant + 长度前缀 + consumer 派生——长度前缀保证不同 (tenant, consumer) 组合拼不出同一个键(consumer 里出现任何分隔符都不影响单射)。

func NewTenantTailCursorStore added in v0.43.0

func NewTenantTailCursorStore(pool *pgxpool.Pool, consumer string) *TenantTailCursorStore

NewTenantTailCursorStore 构造租户作用域游标存储。pool 不得为 nil, consumer 不得为空(装配期编程错误 fail fast,与 NewTailCursorStore 同口径)。

func (*TenantTailCursorStore) LoadCursor added in v0.43.0

func (s *TenantTailCursorStore) LoadCursor(ctx context.Context) (uint64, bool, error)

LoadCursor 读当前租户上次保存的游标(缺租户上下文 ⇒ tenant.ErrNoContext)。

func (*TenantTailCursorStore) SaveCursor added in v0.43.0

func (s *TenantTailCursorStore) SaveCursor(ctx context.Context, cursor uint64) error

SaveCursor 保存当前租户的游标(缺租户上下文 ⇒ tenant.ErrNoContext)。

Directories

Path Synopsis
cmd
pgsmoke command
Command pgsmoke 参考部署的**冒烟入口**:一个宿主进程连上 PostgreSQL, 把副作用闸 + 栅栏下游 + 任务认领的关键判据各走一遍,全部通过即退出 0。
Command pgsmoke 参考部署的**冒烟入口**:一个宿主进程连上 PostgreSQL, 把副作用闸 + 栅栏下游 + 任务认领的关键判据各走一遍,全部通过即退出 0。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL