用于跟踪数据库模式变更的API - Neon

简介

在现代软件开发中，数据库模式的变更管理是一个重要但复杂的任务。为了简化这一过程，Neon 提供了 Schema Diff 功能，用于便捷地比较 Neon 数据库之间的模式差异。最初，这一功能通过 Neon 控制台和 CLI 提供，而近期通过发布 Schema Diff GitHub Action，进一步将其能力扩展到开发者的日常工作流中。本文将介绍该功能的应用场景及其背后的技术支持。

Schema Diff GitHub Action 的功能与优势

Schema Diff GitHub Action 将模式差异直接集成到拉取请求（Pull Request）流程中。每当创建或更新拉取请求时，该 GitHub Action 会自动执行模式比对，并在 PR 中生成差异摘要的评论。这种自动化的方式不仅提升了开发效率，还减少了人为错误的可能性。

在交付 GitHub Action 后，Neon 计划通过 API 将这些自动化能力扩展到其他 CI/CD 流水线中，以满足更广泛的使用需求。

模式差异检查 API 的新应用场景：智能体系统

什么是智能体系统？

智能体系统是一种由大语言模型驱动的自主 AI 实体，能够动态决策以实现复杂目标。例如，它们可以部署软件基础设施来构建端到端应用。与传统的静态 AI 工作流不同，智能体系统可以根据当前任务动态适应和调整。

智能体系统与数据库模式演进

在部署功能型应用时，持久化数据存储是智能体系统不可或缺的一部分。例如，Replit Agent 能够根据项目需求部署和管理 Postgres 数据库。然而，当数据结构需要变更（如新增功能）时，智能体系统必须能够评估当前的 Postgres 模式，确定必要的更新并实施变更。

compare_schema API 的作用

compare_schema API 为智能体系统提供了编程式的模式比对能力，简化了数据库模式演进的流程。例如，Replit Agent 可以利用该 API 实现以下功能：

• 在实施新功能时动态评估模式差异。

这种功能不仅对智能体系统有益，对开发者同样适用。开发者可以利用该工具增强流水线的自动化能力，从而优化工作效率。

数据库迁移的自动化：结合 Neon 分支与 compare_schema API

数据库迁移是开发过程中最难自动化的环节之一，通常包括以下步骤：

1. 对比当前模式与目标模式，识别差异。
2. 编写迁移脚本以对齐两者。
3. 测试迁移的有效性。

通过结合 Neon 分支与 compare_schema API，这些步骤可以被有效自动化。团队可以建立如下工作流：

1. 在 Neon 分支中应用并测试模式变更。Neon 分支包含生产数据的副本，但独立运行。
2. 在测试过程中，确保新模式能够正常处理真实数据，从而降低错误风险。
3. 在验证通过后，将变更平滑地部署到生产环境。

这种方法不仅降低了数据库迁移的复杂性，还提升了开发效率和可靠性。

compare_schema API 的使用方法

API 参数说明

compare_schema API 接收两个 Neon 分支 ID，并返回突出显示数据库对象增删改的模式差异。支持的参数包括：

• project_id：Neon 项目 ID。
• 时间点参数：包括 LSN 和时间戳（两者互斥），用于指定分支历史的不同时间节点。

示例：使用 cURL 比较分支模式

以下是一个使用 cURL 命令比较目标分支（br-rough-boat-a54bs9yb）与基准分支（br-royal-star-a54kykl2）模式的示例：

curl -X POST https://api.neon.tech/compare_schema 
-H "Authorization: Bearer " 
-d '{
  "project_id": "",
  "source_branch_id": "br-royal-star-a54kykl2",
  "target_branch_id": "br-rough-boat-a54bs9yb"
}'

输出结构示例

以下是 API 返回的模式差异示例：

--- a/neondb
+++ b/neondb
@@ -27,7 +27,8 @@
 CREATE TABLE public.playing_with_neon (
   id integer NOT NULL,
   name text NOT NULL,
-  value real
+  value real,
+  created_at timestamp without time zone DEFAULT CURRENT_TIMESTAMP
);

• (-) 标记的行表示基准分支中被删除的模式元素。
• (+) 标记的行表示目标分支中新增的模式元素。

总结

Neon 的 Schema Diff 功能及其扩展的 compare_schema API，为开发者和智能体系统提供了强大的工具，简化了数据库模式管理的复杂性。通过将模式比对集成到 CI/CD 流水线或智能体系统中，开发团队可以更高效地处理数据库迁移任务，同时降低错误风险。未来，随着更多功能的引入，Neon 有望进一步提升开发者的工作效率，为数据库管理带来更多创新解决方案。

原文链接: https://neon.tech/blog/api-track-schema-changes