pgschema - 像 Terraform 一样管理 PostgreSQL schema
数据库 migration 工具常常把团队推向两种极端：要么每次手写带编号的 SQL migration，要么把 schema 变化绑进 ORM 的抽象里。前者透明但容易累积顺序和回滚负担，后者省事但一旦遇到数据库特性，常常又要回到手写 SQL。
今天推荐的 pgplex/pgschema 给 PostgreSQL 提供了另一种路径：像 Terraform 管基础设施一样，用一个声明式 schema 文件表达“数据库应该长什么样”，再由 CLI 对比当前数据库、生成计划并执行变更。
发布时 GitHub 页面显示项目约 939 stars、55 forks，主要语言是 Go，许可是 Apache-2.0。仓库创建于 2025-06-08，最近仍在活跃更新；GitHub releases 页面显示最新版本为 v1.10.0，发布时间是 2026-05-30。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | pgplex/pgschema |
| 定位 | PostgreSQL 声明式 schema migration CLI |
| Stars | 约 939 |
| Forks | 55 |
| 主要语言 | Go |
| 许可 | Apache-2.0 |
| Latest release | v1.10.0 |
核心工作流很像 Terraform
pgschema 的主线流程可以概括成四步：
- 从现有 PostgreSQL 实例 dump 出 schema。
- 在普通 SQL 文件里编辑目标结构。
- 运行 plan，查看将要执行的 DDL。
- 确认后 apply，把变更应用到数据库。
这点和传统 migration 文件最大的差异在于：开发者不需要先决定“第 042 个 migration 文件要写什么”。你维护的是目标状态，工具负责计算从当前状态到目标状态的路径。
这并不意味着 migration 风险消失了。数据库 DDL 仍然可能锁表、失败或影响线上写入。但 plan 阶段会把变更以人能读懂的方式列出来，团队可以把它放进 pull request、CI 或发布流程里审查，而不是直接把一段手写 SQL 丢给生产环境。
它选择了 PostgreSQL 专精
很多 migration 工具为了覆盖多种数据库，会牺牲一部分数据库特有能力。pgschema 反过来选择只服务 PostgreSQL，因此可以处理更细的对象类型。
README 中列出的覆盖面包括表、约束、索引、视图、物化视图、函数、存储过程、触发器、序列、枚举和复合类型、domain、row-level security policy、权限、default privileges、comments 等。它还强调支持 PostgreSQL 14 到 18。
这对真实业务很关键。很多团队并不是只有 CREATE TABLE 和普通索引。只要用到了 RLS、partial index、partitioned table、constraint trigger 或 column-level grant，通用 migration 工具就可能让你退回手写 SQL。pgschema 的价值就在于尽量把这些 PostgreSQL 原生能力纳入同一套 diff 和 plan 流程。
Plain SQL 比 DSL 更容易审查
pgschema 不是让你学一套新的 schema DSL，而是继续使用 SQL 文件表达目标结构。这一点很实际。
数据库 schema 是团队里很多角色都会看的东西：后端工程师、DBA、SRE、数据工程师，甚至安全审计人员。SQL 虽然冗长，但它是大家能共同审查的语言。把目标 schema 放在 Git 里，也让变更历史更直接。
如果团队已经有 schema.sql、数据库 dump 或手写 DDL 习惯，pgschema 的迁移阻力会比引入专有 DSL 小。你可以先让它参与 plan 和审查，不必一次性重写整个数据库工作流。
Plan 阶段适合放进 CI
声明式 migration 的关键不只是“自动生成 SQL”，而是把风险提前暴露出来。pgschema 的 plan 输出既可以给人看，也可以输出 JSON。这让它适合进入 CI：
- pull request 修改了 schema 文件；
- CI 连接一个测试数据库或受控环境；
- pgschema 生成 plan；
- 评审者查看新增列、索引、权限或 policy 变化；
- 只有 plan 被接受后才进入 apply。
这种模式对中小团队尤其有用。它不要求你一开始就建立完整的数据库发布平台，却能先把 schema 变更从“某个人本地跑了一段 SQL”推进到“变更可预览、可记录、可讨论”。
对 AI coding workflow 的意义
pgschema 的 README 特别提到 AI-assisted workflow，并提供面向 LLM 上下文的文档入口。这个设计不是噱头，它确实解决了一个常见问题：agent 能写应用代码，但不一定能可靠地判断数据库结构变更会产生什么实际 DDL。
如果 schema 变更只存在于自然语言需求和 ORM model diff 之间，agent 很容易漏掉约束、权限或索引影响。pgschema 把目标 schema、plan 和 JSON 输出放在一起，相当于给 agent 一个更可验证的边界：
- 它可以修改 SQL schema 文件；
- 它可以读取 plan，知道实际会执行什么；
- 它可以把 plan 摘要写回 PR；
- 它可以在失败时围绕具体 DDL 修复，而不是猜测 ORM 行为。
这并不是让 agent 自动改生产数据库。更稳妥的用法是：让 agent 参与草拟和解释变更，人类继续掌握 apply 的时机和权限。
使用前需要注意的边界
pgschema 目前明确面向 PostgreSQL，不是跨数据库 migration 层。如果你的系统同时覆盖 MySQL、SQLite 和 Postgres，它不适合作为唯一标准。
README 也提示 Windows 不直接支持，需要 WSL 或 Linux VM。这对本地全 Windows 团队是一个现实门槛，不过对多数 CI 和服务器环境影响不大。
另外，声明式 schema 工具并不能替代数据迁移设计。比如拆字段、回填数据、分阶段上线、无锁索引、蓝绿发布等问题，仍然需要工程判断。pgschema 更适合管理结构状态和 DDL 计划，不应该被当成自动化发布全部数据库变更的万能按钮。
适合什么团队
我会优先在这些场景里试 pgschema：
- 主要数据库是 PostgreSQL，并且想把 schema 放进 Git 管理。
- 已经厌倦手写编号 migration，但又不想把 schema 完全交给 ORM。
- 需要 RLS、partition、partial index、trigger、grant 等 PostgreSQL 特性。
- 希望在 PR 或 CI 中看到类似
terraform plan的数据库变更预览。 - 正在让 AI coding agent 参与后端开发，需要更可审查的数据库变更证据。
如果团队已经稳定使用 Flyway、Liquibase 或 Atlas，也不一定需要迁移。pgschema 更适合那些想保留 SQL 可读性，同时减少手写 migration 顺序负担的团队。
小结
pgplex/pgschema 的价值在于把 PostgreSQL schema migration 拉回到一个清楚的循环里：目标状态写在 SQL，变更计划可以预览，执行步骤可确认，结果可以纳入 Git 和 CI。
它不是最通用的数据库工具，而是一个很明确的 PostgreSQL 工具。对需要 Postgres 原生能力、又想改善 migration 审查体验的团队来说，这种专精反而是优点。