消息队列后端通信【免费下载链接】centrifugoScalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably, socket.io, Phoenix.PubSub, SignalR. Set up once and forever.项目地址https://gitcode.com/gh_mirrors/ce/centrifugo点击查看免费下载Centrifugo 的 PostgreSQL MapBroker 是一个基于 PostgreSQL 实现持久化 Map 订阅的 Broker它把协作画板、文档协同、库存预订、游戏大厅等有状态实时场景的键值快照 变更历史落到 SQL 中。本文以仓库文档 internal/pgmapbroker/internal/sql/migrations/postgres_schema.md 为核心骨架结合 pgmapbroker.go、pgschema.go 与 schema.sql 的源码实现系统讲解其 Schema 自动管理EnsureSchema()、双变体建表、整数版本化迁移、滚动部署规则与迁移开发工作流读完你可以安全地在多节点集群上管理该 Broker 的 PostgreSQL 结构演进。一、为什么需要一套独立的 Schema 管理机制PostgreSQL MapBroker 的核心数据模型是一组配套的表与 PL/pgSQL 函数prefixstream分区变更流、prefixstate当前快照、prefixmeta流元数据、prefixidempotency幂等表、prefixshard_lock分片锁、prefixschema_version版本表以及publish/publish_strict/remove/remove_strict/expire_keys等函数。这些对象是 Broker 正常工作的结构基础但与传统手动执行迁移脚本的管理方式不同MapBroker 选择在进程启动时自动完成结构的创建与升级——这就是EnsureSchema()的职责。从源码看它有以下核心设计决策一次调用同时创建两套 Schema无论BinaryData配置如何EnsureSchema()都会同时创建 JSONB 与 BYTEA 两个变体的表与函数见 pgmapbroker.go 的注释与实现保证任意时刻切换存储类型都无需重建结构。使用整数版本化版本号存放在cf_map_schema_version与cf_binary_map_schema_version两张表中支持向前迁移forward migrations。启动时自动收敛版本匹配则跳过全部 DDL快速路径版本落后则先执行迁移、再重放幂等 DDL。该机制全部位于 Centrifugo 的 internal/pgmapbroker/ 目录其共享原语版本读取、迁移锁、事务化迁移、降级拒绝被抽取到 internal/pgschema/pgschema.go供所有 PostgreSQL 后端如 pgstreambroker、Postgres controller复用避免各组件各自实现导致语义漂移。二、EnsureSchema 能自动处理哪些结构变更文档给出了一张关键的能力边界表它划定了自动 vs 需要人工迁移的分界线变更类型处理机制是否需要迁移新增表CREATE TABLE IF NOT EXISTS否新增索引CREATE INDEX IF NOT EXISTS否函数体修改CREATE OR REPLACE FUNCTION否新增带 DEFAULT 的函数参数CREATE OR REPLACE FUNCTION否既有表新增列--是ALTER TABLE ADD COLUMN IF NOT EXISTS列类型变更--是ALTER TABLE ALTER COLUMN TYPE函数签名变更参数/返回类型--是DROP FUNCTIONCREATE删除列--是两阶段先停止使用再 DROP这张表的判断依据直接体现在 schema.sql 中——所有语句都是幂等构造CREATE TABLE IF NOT EXISTS、CREATE INDEX IF NOT EXISTS、CREATE OR REPLACE FUNCTION因此重放全量 DDL 是无害的。函数体或新增带默认值参数可以靠CREATE OR REPLACE无痛升级而列级变更新增列、改类型、删列无法用幂等 DDL 表达必须走迁移链。值得强调的是函数签名变更参数类型、返回类型改变无法用CREATE OR REPLACE完成必须DROP FUNCTION后重新CREATE。这也是滚动部署中唯一可能产生瞬时报错的场景详见下文第五部分。三、双变体建表JSONB 与 BYTEA 并存MapBroker 的BinaryData配置决定运行时使用哪套存储false默认用 JSONB 列适合合法 JSON 负载并支持 JSONB 查询true用 BYTEA 列适合二进制 / protobuf 等非 JSON 负载。但EnsureSchema()会同时维护两套结构而不是只建当前生效的一套。3.1 命名规则从 newPgNames 可以看出前缀推导逻辑用户配置TablePrefix默认cf末尾下划线会被strings.TrimRight去掉Broker 在其后拼接角色组件jsonbPrefix TablePrefix _map_ → 默认 cf_map_ binaryPrefix TablePrefix _binary_map_ → 默认 cf_binary_map_由此派生出全部表名与函数名以活跃变体为准对象名称默认前缀示例变更流表cf_map_stream/cf_binary_map_stream快照表cf_map_state/cf_binary_map_state元数据表cf_map_meta/cf_binary_map_meta幂等表cf_map_idempotency/cf_binary_map_idempotency分片锁表cf_map_shard_lock/cf_binary_map_shard_lock版本表cf_map_schema_version/cf_binary_map_schema_version发布函数cf_map_publish/cf_binary_map_publish通知频道cf_map_stream_notify/cf_binary_map_stream_notify多租户共享同一 PostgreSQL 实例时可以用不同前缀区分集群例如prod_us_cf、prod_eu_cf见 pgmapbroker.go 的TablePrefix注释。另外未来基于 PostgreSQL 的流式 Broker 使用同样的默认前缀cf但拼接自己的角色组件_stream_因此两者即使指向同一数据库也不会冲突。3.2 模板渲染与占位符schema.sql 并非可直接执行的 DDL而是一个模板通过//go:embed嵌入二进制见 pgmapbroker.go运行时由 renderSchemaTemplate 替换两个占位符__PREFIX__→cf_map_或cf_binary_map_或用户自定义前缀__DATA_TYPE__→JSONB或BYTEAEnsureSchema()会分别渲染 JSONB 与 BYTEA 两套 SQL 并全部执行见 EnsureSchema这正是一次调用同时创建双变体的实现位置。四、整数版本化与启动路径快速路径 / 全新安装 / 升级4.1 版本存储与读取版本表结构非常简单见 schema.sqlCREATE TABLE IF NOT EXISTS __PREFIX__schema_version ( id INTEGER PRIMARY KEY, schema_version INTEGER NOT NULL ); INSERT INTO __PREFIX__schema_version (id, schema_version) VALUES (1, 1) ON CONFLICT (id) DO NOTHING;启动时通过pgschema.ReadSchemaVersion读取pgschema.go它做了错误类别区分这一点非常关键读到版本号 → 正常返回(version, isFreshfalse)表不存在PostgreSQL 错误码42P01或行不存在pgx.ErrNoRows→ 视为全新安装(0, isFreshtrue)其他错误连接抖动、权限不足、超时、列缺失→必须向上传播绝不能当作全新安装处理源码注释解释了原因如果临时 SELECT 失败被当作 fresh会跳过迁移链、最终UPDATE schema_version强行把版本号推高导致表结构停留在旧形态、版本行却声称新版本的静默损坏。4.2 三条启动路径EnsureSchema()的完整流程pgmapbroker.go可以归纳为文档所述的三条路径快速路径Fast Path版本匹配且双变体的主表都存在时跳过全部 DDL只做两件事reconcileShardLock()——让shard_lock表与当前NumShards严格对齐INSERT ... generate_series(0, $1-1) ON CONFLICT DO NOTHING补齐缺失分片再DELETE ... WHERE shard_id $1裁剪多余分片。这不是性能优化而是功能正确性要求shard_lock缺行会破坏逐分片发布串行化导致流 ID 乱序提交、outbox 游标跳行见 pgmapbroker.go 的注释。ensurePartitionedStream()——补齐分区前瞻窗口。分区是 Schema 中唯一会过期的部分分区前瞻由日历驱动集群停机超过PartitionLookaheadDays后今日分区可能缺失快速路径必须立即补上否则发布会报no partition for value直到分区 worker 下一个 tick见 pgmapbroker.go。快速路径的探测不是只看活跃变体而是同时探测两个变体bothVariantsPresentpgmapbroker.go。原因是两套变体由两次独立的 Exec 创建部分安装可能只提交了一个变体只探测活跃变体会误入快速路径然后在触碰双变体的reconcileShardLock处卡死而本可依赖幂等 DDL 自愈。全新安装Fresh Install版本表不存在 → 跳过迁移循环无旧版本可升级直接渲染并执行最新形态的 DDL最后SetSchemaVersion把版本从 DDL 初始化的 1 提升到当前schemaVersion。DDL 中的INSERT ... VALUES (1,1) ON CONFLICT DO NOTHING保证了基线行存在见 pgmapbroker.go。升级Upgrade版本落后 → 先执行迁移链从dbVersion1到schemaVersion再重放幂等 DDL最后版本号写入对升级而言迁移事务已写入版本该 UPDATE 是 no-op。4.3 为什么迁移必须先于 DDLEnsureSchema的注释pgmapbroker.go解释了顺序原因schema.sql模板反映的是最终形态可能包含CREATE INDEX IF NOT EXISTS idx ON tbl(newcol)这类引用新列的语句——解析索引定义要求新列已经存在。先跑迁移保证 DDL 引用的列都已就位。五、pgschema 共享原语并发安全与降级拒绝EnsureSchema()本身只是编排层真正的并发安全机制都在 internal/pgschema/pgschema.go 中这也是文档所述滚动部署安全的底层支撑迁移前的集群级互斥AcquireMigrationLock 使用 PostgreSQL advisory lock 串行化迁移链。锁 ID 由FNV-64(pgschema/migration: label)推导pgmapbroker与pgstreambroker标签不同、互不阻塞。实现细节持锁连接从池中单独取出并贯穿锁生命周期解锁时显式pg_advisory_unlock后再归还连接避免锁被池内下一个使用者继承连接崩溃时 PostgreSQL 会在会话结束时自动释放锁不会遗留。锁内重读版本runMigrationsUnderLock 在拿到锁后重新读取schema_version——等待锁期间其他节点可能已完成升级同时锁内二次执行CheckDowngrade防止等待期间数据库被更新版本的二进制推进。迁移与版本号同事务ApplyMigrationInTx 对每个变体先执行迁移 SQL、再UPDATE schema_version v两者在同一个事务内提交。任一变体失败则整体回滚包括部分版本号提升因此迁移天然可重试不要求迁移 SQL 本身绝对幂等。迁移只对40P01死锁与XX000并发CREATE OR REPLACE的 tuple concurrently updated重试最多 3 次、间隔 200ms——重复对象错误被视为真实 bug绝不吞掉。DDL 重试策略RetrySchemaExec 最多 5 次尝试、指数退避100ms → 800ms 封顶并带抖动抖动是为了让同时启动的节点错开碰撞。可重试错误码见 IsRetryableSchemaExecErr40P01死锁、XX000内部错误并发替换函数时出现、42P07重复表、42710重复对象、23505唯一冲突——后三类是IF NOT EXISTS探测与加锁之间出现竞态时的正常现象。重试的前提是一个多语句 Exec 整体构成一个隐式事务pgx 对无参数批处理走简单查询协议失败整体回滚因此 DDL 批处理内不得出现显式BEGIN/COMMIT或CREATE INDEX CONCURRENTLY后者的 25001 错误无法在事务块内执行。这条不变式由测试 schema_template_test.go 用正则钉死模板中不允许出现CONCURRENTLYDDL 半段不允许出现事务控制语句。降级拒绝CheckDowngrade 在数据库版本高于二进制支持版本时报错要求运行不低于dbVersion的二进制或恢复旧快照——旧版二进制无法回滚新版迁移对表结构的改动。六、滚动部署规则运维必读文档给出的六条规则是生产环境升级的准则每一条都能在上文源码中找到对应机制加法变更安全新列带 DEFAULT、函数新增带 DEFAULT 参数——旧节点忽略、新节点使用混合版本集群可安全共存。对应CREATE OR REPLACE FUNCTION与ALTER TABLE ADD COLUMN IF NOT EXISTS的幂等性。破坏性变更必须两阶段第一阶段部署停止使用旧列的新代码第二阶段再部署 DROP 迁移。EnsureSchema保证两阶段之间版本不匹配时的行为可预测。函数签名变更需要协调因为必须DROP FUNCTIONCREATE两个选项——接受 1s 的瞬时报错或使用新函数名实现零停机。从源码看publish / remove 函数都有配套的_strict变体新增语义时新增函数名是常见做法。EnsureSchema 每次启动执行一次并发执行安全幂等 DDL 死锁重试。注意 EnsureSchema 的步骤 4 先迁移后 DDL 且迁移在 advisory lock 内、DDL 在锁外锁内迁移、锁外幂等 DDL 的配合正是多节点并发启动的基石。NumShards 变更必须整机重启不能滚动不同 NumShards 的节点并发时会竞争shard_lock填充reconcileShardLock每次启动都会执行混跑会导致分片集合不一致。回滚降级安全EnsureSchema会把函数覆盖回旧版本新版迁移新增的列会被旧代码忽略无数据丢失——但注意这与第 5 点降级拒绝并不矛盾结构降级回到旧二进制、让新列闲置安全而版本号回退新库配旧二进制时旧二进制无法理解新结构会被CheckDowngrade拒绝。七、手动迁移路径不使用自动建表时文档提供了不依赖EnsureSchema的手工管理路径适合已经用外部工具如 Flyway、自定义 CI 脚本管理 Schema 的团队全新安装应用基线 DDL。文档描述的路径为应用internal/pgmapbroker/internal/sql/schema_all.sql在当前仓库中实际产物是模板 internal/pgmapbroker/internal/sql/schema.sql通过go:embed内嵌运行时替换占位符手工执行时需按 JSONB 变体cf_map_/JSONB与 BYTEA 变体cf_binary_map_/BYTEA各渲染一次。查看版本SELECT schema_version FROM cf_map_schema_version WHERE id 1;BYTEA 变体则查cf_binary_map_schema_version。按顺序应用迁移迁移文件位于 internal/pgmapbroker/internal/sql/migrations/按目标版本号依次执行。EnsureSchema 可选保留安全版本匹配时是 no-op禁用也安全由外部工具接管。八、新增迁移的开发者工作流文档为开发者定义了完整的六步流程每一步都有源码落点提升schemaVersion修改 pgmapbroker.go 的var schemaVersion 1。创建迁移文件在 internal/pgmapbroker/internal/sql/migrations/ 新建NNN.sql——显式针对两个前缀编写 SQL且必须幂等。注意当前仓库的迁移目录下尚无任何NNN.sql文件版本 1 是基线迁移从版本 2 开始注册意味着如果你提交新迁移它将是第一个。注册到schemaMigrationsmap在 pgmapbroker.go 的var schemaMigrations map[int]string{}中增加条目并 embed 文件。这里有一个启动期硬校验包级init()调用pgschema.ValidateMigrationMappgschema.go2..schemaVersion中任何版本缺失或越界都会直接 panic——这是为了防止版本号被SetSchemaVersion推高、结构却停留在旧形态的静默损坏。更新schema.sql模板让全新安装只跑 DDL、不跑迁移链直接得到最终形态。运行make pg-schemas重新生成文档约定命令。守住不变式全新安装DDL与升级迁移链必须收敛到完全一致的结构。这条不变式由ValidateMigrationMap的 contiguity 校验与各 consumer 包中的 schema 模板测试共同钉住。迁移的执行细节值得注意EnsureSchema渲染迁移模板时migrationVariantspgmapbroker.go会把同一份迁移 SQL 渲染成 JSONB BYTEA 两个变体并在同一个事务里同时应用并推进两边的版本表——所以迁移作者无需为两个前缀分别写两遍带版本更新的迁移尽管文档约定要求显式写两个前缀的 DDL 语句本身。九、迁移文件约定与示例迁移文件是纯 SQL显式针对两个前缀书写不包含模板占位符——文档的理由很直接生产迁移中显式优于隐式占位符替换出错的风险不值得冒。约定如下与 migrations/README.md 一致文件名NNN.sqlNNN为目标版本号如002.sql版本 1 是基线由schema.sql全量 DDL 应用迁移从 2 开始所有迁移必须幂等ADD COLUMN IF NOT EXISTS等所有迁移必须向后兼容迁移后旧代码仍能正常工作每条迁移必须同时作用于cf_map_*与cf_binary_map_*两个前缀。文档给出的标准示例-- Migration 002: Add foo column ALTER TABLE cf_map_state ADD COLUMN IF NOT EXISTS foo TEXT; ALTER TABLE cf_binary_map_state ADD COLUMN IF NOT EXISTS foo TEXT;结合 schema.sql 中真正的表结构可以想象一个真实的迁移长什么样例如给state表加一个带默认值的列-- Migration 002: Add priority column with default ALTER TABLE cf_map_state ADD COLUMN IF NOT EXISTS priority SMALLINT NOT NULL DEFAULT 0; ALTER TABLE cf_binary_map_state ADD COLUMN IF NOT EXISTS priority SMALLINT NOT NULL DEFAULT 0;幂等 双前缀 带默认值恰好满足加法变更安全的滚动部署规则旧节点忽略新列新节点写入时获得默认值。十、Schema 背后的数据模型速览为了让上文哪些结构变更需要迁移更有体感这里概览 schema.sql 中的核心对象均以__PREFIX__占位符书写运行时会渲染为实际前缀__PREFIX__stream变更流表总是按created_at做每日 RANGE 分区无开关分区是结构性的复合主键(id, created_at)PostgreSQL 要求分区键必须包含在每个唯一约束中。初始分区由pgoutbox.Partitioner前瞻创建保留策略由PartitionRetentionDays控制。索引覆盖(channel, epoch, channel_offset)支持直接越过死 epoch 行、(channel, id DESC)、(shard_id, id)、(created_at)。__PREFIX__state快照表主键(channel, key)保存当前键值、版本、偏移、TTL 等。__PREFIX__meta元数据表每 channel 一行记录top_offset与epoch。__PREFIX__idempotency幂等表主键(channel, idempotency_key)同时保存result_offset与result_epoch——回放时必须返回发布提交时的 epoch而不是回放时 meta 里活着的 epoch否则幂等抑制的回复会让调用方在历史中定位不到那条发布。__PREFIX__shard_lock分片锁表每分片一行EnsureSchema保证与NumShards对齐。__PREFIX__schema_version版本表本文主题的核心(id1, schema_version)单行。函数publish含幂等/版本/CAS/KeyMode 检查、逐分片串行化、写流、pg_notify唤醒 outbox、publish_strict抑制即抛错并自动回滚、remove、remove_strict、expire_keys批量过期并原子推进偏移。其中publish函数内部是单事务的完整流程加 shard 锁 → UPSERT meta并发安全地取得top_offset与epoch→ 幂等检查 → 版本检查 → KeyMode 检查 → CAS 检查 → 推进偏移 → 更新快照 → 插入流 → 写幂等记录 →pg_notify。这也是为什么 Schema 结构尤其是函数签名与 Broker 语义深度耦合——任何参数或返回类型变化都必须走迁移或换函数名。十一、总结PostgreSQL MapBroker 的 Schema 管理可以概括为一句话用幂等 DDL 整数版本迁移 集群级迁移锁的组合让多节点滚动部署下的结构演进既自动又安全。表 / 索引 / 函数体的增改靠幂等 DDL 自动收敛列级变更、签名变更、删列靠版本化迁移且迁移与版本号同事务、跨双变体原子提交多节点并发由 advisory lock迁移与带抖动的重试DDL双保险快速路径让已对齐的集群零开销启动shard_lock对齐与分区前瞻是快速路径上不可省略的收敛动作。对运维者牢记加法变更可滚动、破坏性变更两阶段、NumShards 变更整机重启、函数签名变更需协调四条铁律对开发者新增迁移务必同时更新schemaVersion、schemaMigrations与schema.sql三处并守住全新安装与升级结果一致的不变式——ValidateMigrationMap的启动 panic 会在第一时间提醒你漏了哪一环。赞分享消息队列后端通信【免费下载链接】centrifugoScalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably, socket.io, Phoenix.PubSub, SignalR. Set up once and forever.项目地址https://gitcode.com/gh_mirrors/ce/centrifugo点击查看免费下载相关推荐Argo Workflows 数据库自动迁移Database Migrations完全指南版本表机制与 MySQL/PostgreSQL 迁移脚本逐步骤解析Argo Workflows 数据库自动迁移Database Migrations完全指南版本表机制与 MySQL/PostgreSQL 迁移脚本逐步骤解云原生容器编排工作流自动化任务调度后端WeKnora 数据库 schema 与迁移机制全解PostgreSQL / ParadeDB / SQLite 版本化迁移实战WeKnora 数据库 schema 与迁移机制全解PostgreSQL / ParadeDB / SQLite 版本化迁移实战 WeKnora 是一个开源的人工智能大模型RAGAI Agent后端前端MCP 服务知识库dsh-plugin工具调用Vapor数据库迁移自动化迁移脚本和版本控制Vapor数据库迁移自动化迁移脚本和版本控制 还在手动执行SQL脚本来更新数据库结构还在为团队协作中的数据库版本冲突而头疼Vapor框架结合Fluent后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Centrifugo PostgreSQL MapBroker 架构解析：EnsureSchema 自动建表与整数版本化迁移机制
消息队列后端通信【免费下载链接】centrifugoScalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably, socket.io, Phoenix.PubSub, SignalR. Set up once and forever.项目地址https://gitcode.com/gh_mirrors/ce/centrifugo点击查看免费下载Centrifugo 的 PostgreSQL MapBroker 是一个基于 PostgreSQL 实现持久化 Map 订阅的 Broker它把协作画板、文档协同、库存预订、游戏大厅等有状态实时场景的键值快照 变更历史落到 SQL 中。本文以仓库文档 internal/pgmapbroker/internal/sql/migrations/postgres_schema.md 为核心骨架结合 pgmapbroker.go、pgschema.go 与 schema.sql 的源码实现系统讲解其 Schema 自动管理EnsureSchema()、双变体建表、整数版本化迁移、滚动部署规则与迁移开发工作流读完你可以安全地在多节点集群上管理该 Broker 的 PostgreSQL 结构演进。一、为什么需要一套独立的 Schema 管理机制PostgreSQL MapBroker 的核心数据模型是一组配套的表与 PL/pgSQL 函数prefixstream分区变更流、prefixstate当前快照、prefixmeta流元数据、prefixidempotency幂等表、prefixshard_lock分片锁、prefixschema_version版本表以及publish/publish_strict/remove/remove_strict/expire_keys等函数。这些对象是 Broker 正常工作的结构基础但与传统手动执行迁移脚本的管理方式不同MapBroker 选择在进程启动时自动完成结构的创建与升级——这就是EnsureSchema()的职责。从源码看它有以下核心设计决策一次调用同时创建两套 Schema无论BinaryData配置如何EnsureSchema()都会同时创建 JSONB 与 BYTEA 两个变体的表与函数见 pgmapbroker.go 的注释与实现保证任意时刻切换存储类型都无需重建结构。使用整数版本化版本号存放在cf_map_schema_version与cf_binary_map_schema_version两张表中支持向前迁移forward migrations。启动时自动收敛版本匹配则跳过全部 DDL快速路径版本落后则先执行迁移、再重放幂等 DDL。该机制全部位于 Centrifugo 的 internal/pgmapbroker/ 目录其共享原语版本读取、迁移锁、事务化迁移、降级拒绝被抽取到 internal/pgschema/pgschema.go供所有 PostgreSQL 后端如 pgstreambroker、Postgres controller复用避免各组件各自实现导致语义漂移。二、EnsureSchema 能自动处理哪些结构变更文档给出了一张关键的能力边界表它划定了自动 vs 需要人工迁移的分界线变更类型处理机制是否需要迁移新增表CREATE TABLE IF NOT EXISTS否新增索引CREATE INDEX IF NOT EXISTS否函数体修改CREATE OR REPLACE FUNCTION否新增带 DEFAULT 的函数参数CREATE OR REPLACE FUNCTION否既有表新增列--是ALTER TABLE ADD COLUMN IF NOT EXISTS列类型变更--是ALTER TABLE ALTER COLUMN TYPE函数签名变更参数/返回类型--是DROP FUNCTIONCREATE删除列--是两阶段先停止使用再 DROP这张表的判断依据直接体现在 schema.sql 中——所有语句都是幂等构造CREATE TABLE IF NOT EXISTS、CREATE INDEX IF NOT EXISTS、CREATE OR REPLACE FUNCTION因此重放全量 DDL 是无害的。函数体或新增带默认值参数可以靠CREATE OR REPLACE无痛升级而列级变更新增列、改类型、删列无法用幂等 DDL 表达必须走迁移链。值得强调的是函数签名变更参数类型、返回类型改变无法用CREATE OR REPLACE完成必须DROP FUNCTION后重新CREATE。这也是滚动部署中唯一可能产生瞬时报错的场景详见下文第五部分。三、双变体建表JSONB 与 BYTEA 并存MapBroker 的BinaryData配置决定运行时使用哪套存储false默认用 JSONB 列适合合法 JSON 负载并支持 JSONB 查询true用 BYTEA 列适合二进制 / protobuf 等非 JSON 负载。但EnsureSchema()会同时维护两套结构而不是只建当前生效的一套。3.1 命名规则从 newPgNames 可以看出前缀推导逻辑用户配置TablePrefix默认cf末尾下划线会被strings.TrimRight去掉Broker 在其后拼接角色组件jsonbPrefix TablePrefix _map_ → 默认 cf_map_ binaryPrefix TablePrefix _binary_map_ → 默认 cf_binary_map_由此派生出全部表名与函数名以活跃变体为准对象名称默认前缀示例变更流表cf_map_stream/cf_binary_map_stream快照表cf_map_state/cf_binary_map_state元数据表cf_map_meta/cf_binary_map_meta幂等表cf_map_idempotency/cf_binary_map_idempotency分片锁表cf_map_shard_lock/cf_binary_map_shard_lock版本表cf_map_schema_version/cf_binary_map_schema_version发布函数cf_map_publish/cf_binary_map_publish通知频道cf_map_stream_notify/cf_binary_map_stream_notify多租户共享同一 PostgreSQL 实例时可以用不同前缀区分集群例如prod_us_cf、prod_eu_cf见 pgmapbroker.go 的TablePrefix注释。另外未来基于 PostgreSQL 的流式 Broker 使用同样的默认前缀cf但拼接自己的角色组件_stream_因此两者即使指向同一数据库也不会冲突。3.2 模板渲染与占位符schema.sql 并非可直接执行的 DDL而是一个模板通过//go:embed嵌入二进制见 pgmapbroker.go运行时由 renderSchemaTemplate 替换两个占位符__PREFIX__→cf_map_或cf_binary_map_或用户自定义前缀__DATA_TYPE__→JSONB或BYTEAEnsureSchema()会分别渲染 JSONB 与 BYTEA 两套 SQL 并全部执行见 EnsureSchema这正是一次调用同时创建双变体的实现位置。四、整数版本化与启动路径快速路径 / 全新安装 / 升级4.1 版本存储与读取版本表结构非常简单见 schema.sqlCREATE TABLE IF NOT EXISTS __PREFIX__schema_version ( id INTEGER PRIMARY KEY, schema_version INTEGER NOT NULL ); INSERT INTO __PREFIX__schema_version (id, schema_version) VALUES (1, 1) ON CONFLICT (id) DO NOTHING;启动时通过pgschema.ReadSchemaVersion读取pgschema.go它做了错误类别区分这一点非常关键读到版本号 → 正常返回(version, isFreshfalse)表不存在PostgreSQL 错误码42P01或行不存在pgx.ErrNoRows→ 视为全新安装(0, isFreshtrue)其他错误连接抖动、权限不足、超时、列缺失→必须向上传播绝不能当作全新安装处理源码注释解释了原因如果临时 SELECT 失败被当作 fresh会跳过迁移链、最终UPDATE schema_version强行把版本号推高导致表结构停留在旧形态、版本行却声称新版本的静默损坏。4.2 三条启动路径EnsureSchema()的完整流程pgmapbroker.go可以归纳为文档所述的三条路径快速路径Fast Path版本匹配且双变体的主表都存在时跳过全部 DDL只做两件事reconcileShardLock()——让shard_lock表与当前NumShards严格对齐INSERT ... generate_series(0, $1-1) ON CONFLICT DO NOTHING补齐缺失分片再DELETE ... WHERE shard_id $1裁剪多余分片。这不是性能优化而是功能正确性要求shard_lock缺行会破坏逐分片发布串行化导致流 ID 乱序提交、outbox 游标跳行见 pgmapbroker.go 的注释。ensurePartitionedStream()——补齐分区前瞻窗口。分区是 Schema 中唯一会过期的部分分区前瞻由日历驱动集群停机超过PartitionLookaheadDays后今日分区可能缺失快速路径必须立即补上否则发布会报no partition for value直到分区 worker 下一个 tick见 pgmapbroker.go。快速路径的探测不是只看活跃变体而是同时探测两个变体bothVariantsPresentpgmapbroker.go。原因是两套变体由两次独立的 Exec 创建部分安装可能只提交了一个变体只探测活跃变体会误入快速路径然后在触碰双变体的reconcileShardLock处卡死而本可依赖幂等 DDL 自愈。全新安装Fresh Install版本表不存在 → 跳过迁移循环无旧版本可升级直接渲染并执行最新形态的 DDL最后SetSchemaVersion把版本从 DDL 初始化的 1 提升到当前schemaVersion。DDL 中的INSERT ... VALUES (1,1) ON CONFLICT DO NOTHING保证了基线行存在见 pgmapbroker.go。升级Upgrade版本落后 → 先执行迁移链从dbVersion1到schemaVersion再重放幂等 DDL最后版本号写入对升级而言迁移事务已写入版本该 UPDATE 是 no-op。4.3 为什么迁移必须先于 DDLEnsureSchema的注释pgmapbroker.go解释了顺序原因schema.sql模板反映的是最终形态可能包含CREATE INDEX IF NOT EXISTS idx ON tbl(newcol)这类引用新列的语句——解析索引定义要求新列已经存在。先跑迁移保证 DDL 引用的列都已就位。五、pgschema 共享原语并发安全与降级拒绝EnsureSchema()本身只是编排层真正的并发安全机制都在 internal/pgschema/pgschema.go 中这也是文档所述滚动部署安全的底层支撑迁移前的集群级互斥AcquireMigrationLock 使用 PostgreSQL advisory lock 串行化迁移链。锁 ID 由FNV-64(pgschema/migration: label)推导pgmapbroker与pgstreambroker标签不同、互不阻塞。实现细节持锁连接从池中单独取出并贯穿锁生命周期解锁时显式pg_advisory_unlock后再归还连接避免锁被池内下一个使用者继承连接崩溃时 PostgreSQL 会在会话结束时自动释放锁不会遗留。锁内重读版本runMigrationsUnderLock 在拿到锁后重新读取schema_version——等待锁期间其他节点可能已完成升级同时锁内二次执行CheckDowngrade防止等待期间数据库被更新版本的二进制推进。迁移与版本号同事务ApplyMigrationInTx 对每个变体先执行迁移 SQL、再UPDATE schema_version v两者在同一个事务内提交。任一变体失败则整体回滚包括部分版本号提升因此迁移天然可重试不要求迁移 SQL 本身绝对幂等。迁移只对40P01死锁与XX000并发CREATE OR REPLACE的 tuple concurrently updated重试最多 3 次、间隔 200ms——重复对象错误被视为真实 bug绝不吞掉。DDL 重试策略RetrySchemaExec 最多 5 次尝试、指数退避100ms → 800ms 封顶并带抖动抖动是为了让同时启动的节点错开碰撞。可重试错误码见 IsRetryableSchemaExecErr40P01死锁、XX000内部错误并发替换函数时出现、42P07重复表、42710重复对象、23505唯一冲突——后三类是IF NOT EXISTS探测与加锁之间出现竞态时的正常现象。重试的前提是一个多语句 Exec 整体构成一个隐式事务pgx 对无参数批处理走简单查询协议失败整体回滚因此 DDL 批处理内不得出现显式BEGIN/COMMIT或CREATE INDEX CONCURRENTLY后者的 25001 错误无法在事务块内执行。这条不变式由测试 schema_template_test.go 用正则钉死模板中不允许出现CONCURRENTLYDDL 半段不允许出现事务控制语句。降级拒绝CheckDowngrade 在数据库版本高于二进制支持版本时报错要求运行不低于dbVersion的二进制或恢复旧快照——旧版二进制无法回滚新版迁移对表结构的改动。六、滚动部署规则运维必读文档给出的六条规则是生产环境升级的准则每一条都能在上文源码中找到对应机制加法变更安全新列带 DEFAULT、函数新增带 DEFAULT 参数——旧节点忽略、新节点使用混合版本集群可安全共存。对应CREATE OR REPLACE FUNCTION与ALTER TABLE ADD COLUMN IF NOT EXISTS的幂等性。破坏性变更必须两阶段第一阶段部署停止使用旧列的新代码第二阶段再部署 DROP 迁移。EnsureSchema保证两阶段之间版本不匹配时的行为可预测。函数签名变更需要协调因为必须DROP FUNCTIONCREATE两个选项——接受 1s 的瞬时报错或使用新函数名实现零停机。从源码看publish / remove 函数都有配套的_strict变体新增语义时新增函数名是常见做法。EnsureSchema 每次启动执行一次并发执行安全幂等 DDL 死锁重试。注意 EnsureSchema 的步骤 4 先迁移后 DDL 且迁移在 advisory lock 内、DDL 在锁外锁内迁移、锁外幂等 DDL 的配合正是多节点并发启动的基石。NumShards 变更必须整机重启不能滚动不同 NumShards 的节点并发时会竞争shard_lock填充reconcileShardLock每次启动都会执行混跑会导致分片集合不一致。回滚降级安全EnsureSchema会把函数覆盖回旧版本新版迁移新增的列会被旧代码忽略无数据丢失——但注意这与第 5 点降级拒绝并不矛盾结构降级回到旧二进制、让新列闲置安全而版本号回退新库配旧二进制时旧二进制无法理解新结构会被CheckDowngrade拒绝。七、手动迁移路径不使用自动建表时文档提供了不依赖EnsureSchema的手工管理路径适合已经用外部工具如 Flyway、自定义 CI 脚本管理 Schema 的团队全新安装应用基线 DDL。文档描述的路径为应用internal/pgmapbroker/internal/sql/schema_all.sql在当前仓库中实际产物是模板 internal/pgmapbroker/internal/sql/schema.sql通过go:embed内嵌运行时替换占位符手工执行时需按 JSONB 变体cf_map_/JSONB与 BYTEA 变体cf_binary_map_/BYTEA各渲染一次。查看版本SELECT schema_version FROM cf_map_schema_version WHERE id 1;BYTEA 变体则查cf_binary_map_schema_version。按顺序应用迁移迁移文件位于 internal/pgmapbroker/internal/sql/migrations/按目标版本号依次执行。EnsureSchema 可选保留安全版本匹配时是 no-op禁用也安全由外部工具接管。八、新增迁移的开发者工作流文档为开发者定义了完整的六步流程每一步都有源码落点提升schemaVersion修改 pgmapbroker.go 的var schemaVersion 1。创建迁移文件在 internal/pgmapbroker/internal/sql/migrations/ 新建NNN.sql——显式针对两个前缀编写 SQL且必须幂等。注意当前仓库的迁移目录下尚无任何NNN.sql文件版本 1 是基线迁移从版本 2 开始注册意味着如果你提交新迁移它将是第一个。注册到schemaMigrationsmap在 pgmapbroker.go 的var schemaMigrations map[int]string{}中增加条目并 embed 文件。这里有一个启动期硬校验包级init()调用pgschema.ValidateMigrationMappgschema.go2..schemaVersion中任何版本缺失或越界都会直接 panic——这是为了防止版本号被SetSchemaVersion推高、结构却停留在旧形态的静默损坏。更新schema.sql模板让全新安装只跑 DDL、不跑迁移链直接得到最终形态。运行make pg-schemas重新生成文档约定命令。守住不变式全新安装DDL与升级迁移链必须收敛到完全一致的结构。这条不变式由ValidateMigrationMap的 contiguity 校验与各 consumer 包中的 schema 模板测试共同钉住。迁移的执行细节值得注意EnsureSchema渲染迁移模板时migrationVariantspgmapbroker.go会把同一份迁移 SQL 渲染成 JSONB BYTEA 两个变体并在同一个事务里同时应用并推进两边的版本表——所以迁移作者无需为两个前缀分别写两遍带版本更新的迁移尽管文档约定要求显式写两个前缀的 DDL 语句本身。九、迁移文件约定与示例迁移文件是纯 SQL显式针对两个前缀书写不包含模板占位符——文档的理由很直接生产迁移中显式优于隐式占位符替换出错的风险不值得冒。约定如下与 migrations/README.md 一致文件名NNN.sqlNNN为目标版本号如002.sql版本 1 是基线由schema.sql全量 DDL 应用迁移从 2 开始所有迁移必须幂等ADD COLUMN IF NOT EXISTS等所有迁移必须向后兼容迁移后旧代码仍能正常工作每条迁移必须同时作用于cf_map_*与cf_binary_map_*两个前缀。文档给出的标准示例-- Migration 002: Add foo column ALTER TABLE cf_map_state ADD COLUMN IF NOT EXISTS foo TEXT; ALTER TABLE cf_binary_map_state ADD COLUMN IF NOT EXISTS foo TEXT;结合 schema.sql 中真正的表结构可以想象一个真实的迁移长什么样例如给state表加一个带默认值的列-- Migration 002: Add priority column with default ALTER TABLE cf_map_state ADD COLUMN IF NOT EXISTS priority SMALLINT NOT NULL DEFAULT 0; ALTER TABLE cf_binary_map_state ADD COLUMN IF NOT EXISTS priority SMALLINT NOT NULL DEFAULT 0;幂等 双前缀 带默认值恰好满足加法变更安全的滚动部署规则旧节点忽略新列新节点写入时获得默认值。十、Schema 背后的数据模型速览为了让上文哪些结构变更需要迁移更有体感这里概览 schema.sql 中的核心对象均以__PREFIX__占位符书写运行时会渲染为实际前缀__PREFIX__stream变更流表总是按created_at做每日 RANGE 分区无开关分区是结构性的复合主键(id, created_at)PostgreSQL 要求分区键必须包含在每个唯一约束中。初始分区由pgoutbox.Partitioner前瞻创建保留策略由PartitionRetentionDays控制。索引覆盖(channel, epoch, channel_offset)支持直接越过死 epoch 行、(channel, id DESC)、(shard_id, id)、(created_at)。__PREFIX__state快照表主键(channel, key)保存当前键值、版本、偏移、TTL 等。__PREFIX__meta元数据表每 channel 一行记录top_offset与epoch。__PREFIX__idempotency幂等表主键(channel, idempotency_key)同时保存result_offset与result_epoch——回放时必须返回发布提交时的 epoch而不是回放时 meta 里活着的 epoch否则幂等抑制的回复会让调用方在历史中定位不到那条发布。__PREFIX__shard_lock分片锁表每分片一行EnsureSchema保证与NumShards对齐。__PREFIX__schema_version版本表本文主题的核心(id1, schema_version)单行。函数publish含幂等/版本/CAS/KeyMode 检查、逐分片串行化、写流、pg_notify唤醒 outbox、publish_strict抑制即抛错并自动回滚、remove、remove_strict、expire_keys批量过期并原子推进偏移。其中publish函数内部是单事务的完整流程加 shard 锁 → UPSERT meta并发安全地取得top_offset与epoch→ 幂等检查 → 版本检查 → KeyMode 检查 → CAS 检查 → 推进偏移 → 更新快照 → 插入流 → 写幂等记录 →pg_notify。这也是为什么 Schema 结构尤其是函数签名与 Broker 语义深度耦合——任何参数或返回类型变化都必须走迁移或换函数名。十一、总结PostgreSQL MapBroker 的 Schema 管理可以概括为一句话用幂等 DDL 整数版本迁移 集群级迁移锁的组合让多节点滚动部署下的结构演进既自动又安全。表 / 索引 / 函数体的增改靠幂等 DDL 自动收敛列级变更、签名变更、删列靠版本化迁移且迁移与版本号同事务、跨双变体原子提交多节点并发由 advisory lock迁移与带抖动的重试DDL双保险快速路径让已对齐的集群零开销启动shard_lock对齐与分区前瞻是快速路径上不可省略的收敛动作。对运维者牢记加法变更可滚动、破坏性变更两阶段、NumShards 变更整机重启、函数签名变更需协调四条铁律对开发者新增迁移务必同时更新schemaVersion、schemaMigrations与schema.sql三处并守住全新安装与升级结果一致的不变式——ValidateMigrationMap的启动 panic 会在第一时间提醒你漏了哪一环。赞分享消息队列后端通信【免费下载链接】centrifugoScalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably, socket.io, Phoenix.PubSub, SignalR. Set up once and forever.项目地址https://gitcode.com/gh_mirrors/ce/centrifugo点击查看免费下载相关推荐Argo Workflows 数据库自动迁移Database Migrations完全指南版本表机制与 MySQL/PostgreSQL 迁移脚本逐步骤解析Argo Workflows 数据库自动迁移Database Migrations完全指南版本表机制与 MySQL/PostgreSQL 迁移脚本逐步骤解云原生容器编排工作流自动化任务调度后端WeKnora 数据库 schema 与迁移机制全解PostgreSQL / ParadeDB / SQLite 版本化迁移实战WeKnora 数据库 schema 与迁移机制全解PostgreSQL / ParadeDB / SQLite 版本化迁移实战 WeKnora 是一个开源的人工智能大模型RAGAI Agent后端前端MCP 服务知识库dsh-plugin工具调用Vapor数据库迁移自动化迁移脚本和版本控制Vapor数据库迁移自动化迁移脚本和版本控制 还在手动执行SQL脚本来更新数据库结构还在为团队协作中的数据库版本冲突而头疼Vapor框架结合Fluent后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考