neon-postgres-branches

Name: neon-postgres-branches
Author: neondatabase

github.com/neondatabase数据与数据库10732.6k 次安装1 天前更新

代码仓库

关于 neon-postgres-branches

面向开发和迁移工作流的 Neon 技能，用于创建和管理 Postgres 分支。它帮助选择含数据或仅含架构的分支，并以 CLI 为首选，同时提供 MCP 和 API 后备路径。

主要功能

01选择普通分支或仅架构分支
02通过 Neon CLI 或 MCP 创建分支
03从父分支重置子分支
04在 neon.ts 中配置分支生命周期
05在 CI 和预览工作流中使用分支

适用场景

01使用接近生产的数据测试迁移
02避免复制敏感行数据进行开发
03从父分支刷新预发布环境
04为拉取请求创建隔离数据库分支

MCP 相关

CLI 不可用、受阻、无法认证或用户明确要求时，此技能支持改用 Neon MCP 服务。它说明如何通过 MCP 工具创建并验证分支。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres-branches

安装后在 Claude Code 中输入/neon-postgres-branches确认已加载。

详细介绍

首先：使用父级 neon 技能了解 Neon、开始使用 Neon、Neon 开发最佳实践等内容。

如果未安装 neon 技能，请从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或通过以下命令安装：

neon skills -s neon -y

Lakebase Postgres 分支

**结果：**创建一个 Neon 分支；如果无法创建，则提供明确且可执行的后续步骤。选择正确的分支类型，然后使用 CLI（或在 CLI 不可用时使用 MCP）创建分支。

普通分支：使用真实数据进行逼真的迁移和查询测试。
仅架构分支（Beta）：适用于需要架构但不能复制行数据的敏感数据工作流。

分支类型选择

首先使用以下规则进行选择：

如果用户想要针对类似生产环境的数据测试复杂迁移、性能或行为，请选择普通分支。
如果用户需要避免复制敏感数据，请选择仅架构分支。

如果请求含糊不清，请提出一个澄清问题： “您需要逼真的测试数据，还是只需要架构结构，因为数据较为敏感？”

工具选择：CLI 或 MCP

同时支持 Neon CLI 和 Neon MCP 服务，但默认使用 CLI。仅当 CLI 在您的环境中不可用或受到阻止、无法通过身份验证，或用户明确要求使用 MCP 时，才使用 MCP。

CLI 链接：https://neon.com/docs/cli/quickstart.md
MCP 链接：https://neon.com/docs/ai/neon-mcp-server.md

选择顺序

首先检查 CLI：
- 运行 neon --version，确认已安装 CLI。
- 运行 neon projects list，确认身份验证和上下文。
如果缺少 CLI，请引导用户通过快速入门进行安装。
如果已安装 CLI 但尚未通过身份验证，请引导用户执行 neon auth（或使用 API 密钥进行身份验证），然后继续。
当 CLI 无法使用时（环境中没有 CLI 访问权限、执行受阻或无法进行身份验证），或者用户明确要求使用 MCP 时，切换到 MCP。确认 Neon MCP 工具可用且已通过身份验证（例如，能够列出项目），然后按照下方的 MCP 分支流程操作。
如果两种方式都无法成功，请使用 Neon REST API：
- https://neon.com/docs/guides/branching-neon-api.md

MCP 分支流程

根据数据敏感性和迁移测试目标，选择普通分支或仅架构分支。
使用分支工具（例如 create_branch）创建分支。
使用读取工具（例如 describe_branch）进行验证。
对于迁移工作流，优先采用基于分支的迁移流程，然后再应用到主分支。

创建普通分支（真实数据迁移测试的首选）

当用户需要逼真的测试条件时使用此方式。真实的类生产数据可以暴露种子脚本或数据迁移脚本遗漏的边缘情况，帮助在正式上线前发现迁移问题。

链接：https://neon.com/docs/introduction/branching.md

步骤

首先确定工具路径（参见选择顺序）：通过 neon --version 验证 CLI，仅当 CLI 不可用时才切换到 MCP。
确保已设置项目上下文（neon set-context --project-id <your-project-id>），或在命令中加入 --project-id。

创建分支：

neon branches create \
  --name <branch-name> \
  --parent <parent-branch-id-or-name> \
  --expires-at 2026-12-15T18:02:16Z

可选：获取新分支的连接字符串：
```
neon connection-string <branch-name>
```

创建仅架构分支（Beta，敏感数据）

当用户不得将生产环境中的行数据复制到测试分支时使用此方式。

链接：https://neon.com/docs/guides/branching-schema-only.md

步骤

首先确定工具路径（参见选择顺序）：通过 neon --version 验证 CLI，仅当 CLI 不可用时才切换到 MCP。

创建仅架构分支：

neon branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --expires-at 2026-12-15T18:02:16Z

如果存在多个项目，请加入 --project-id：

neon branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --project-id <your-project-id> \
  --expires-at 2026-12-15T18:02:16Z

Beta 支持指导（强制）

仅架构分支功能目前处于 Beta 阶段。如果用户报告意外行为、错误或缺失的功能：

请他们在 Neon Console 中提交反馈：
- https://console.neon.tech/app/projects?modal=feedback
建议他们在 Neon Discord 中发起支持对话：
- https://neon.com/discord

从父分支重置

当子分支已偏离父分支，而用户希望使用父分支的最新架构和数据进行干净刷新时，请使用此功能。

链接：https://neon.com/docs/guides/reset-from-parent.md

功能说明

将子分支的架构和数据完全替换为父分支的最新状态。
不会合并；子分支上的本地更改会丢失。
保留相同的连接详细信息，但重置期间活动连接会短暂中断。

建议使用的情况

开发或预发布分支落后于生产环境太多。
用户希望从与父分支一致的干净状态开始开发新功能。
团队希望从生产环境刷新预发布环境，以便使用一致的测试基线。

严格限制和阻碍因素

只能重置子分支（根分支和仅架构根分支无法从父分支重置）。
如果目标分支有子分支，必须先删除这些子分支才能重置。
从快照恢复父分支后，最长 24 小时内可能无法使用从父分支重置。
从父分支重置始终使用父分支的当前状态；如需按时间点恢复，请使用 Instant restore。

CLI 用法

neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>

如果尚未设置项目上下文，请包含项目 ID：

neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>

--preserve-under-name 会将重置前的状态保留为备份分支，以便回滚，但之后需要额外清理一个分支。

可选的上下文设置，可避免重复使用 --project-id：

neon set-context --project-id <project-id>

Console 和 API 用法

**Console：**打开目标子分支，然后从 Actions 中选择 Reset from parent。
**API：**使用该分支的恢复端点，并将 source_branch_id 设置为父分支 ID。

注意事项和限制

仅架构分支用于仅克隆结构，以及敏感数据和合规数据控制。
仅架构分支是独立的根分支（没有父分支，也没有共享历史记录），因此不适用从父分支重置。
对于依赖真实行结构、数据量和边缘情况的迁移测试，优先使用普通分支。
根分支配额和每个分支的存储限制可能会限制用户可创建的仅架构分支数量。
如果用户不确定，默认建议如下：
- 普通分支用于迁移验证。
- 仅架构分支用于满足合规和隐私限制。

实用工作流模式

如果用户询问流程建议（而非单条命令），请建议以下做法：

**每个 PR 使用一个分支：**PR 创建时创建分支，合并或关闭时删除分支，并隔离迁移测试。
**每次测试运行使用一个分支：**在流水线启动时创建分支，运行迁移和测试，并在结束时删除分支，以实现确定性的 CI。
**每位开发者使用一个分支：**使用与生产环境结构相似的隔离开发环境；避免团队成员在共享测试数据上发生冲突。
**考虑 PII 的分支管理：**如果生产环境包含敏感数据，请从匿名化分支派生开发和 PR 分支，或使用仅架构分支。
**临时分支生命周期管理：**设置分支过期时间并自动清理，避免旧分支不断累积不必要的存储和历史记录成本。

创建后环境更新提示

创建分支后，询问用户是否要更新本地环境凭据，使其指向新分支。

询问：“你要我将 .env 中的 DATABASE_URL 更新为这个新分支的连接字符串吗？”
如果是，将新分支的连接字符串写入指定的环境文件或键。
如果否，保持凭据不变，并提供连接字符串供其手动使用。
未经明确确认，绝不覆盖现有环境键。

Neon 基础设施即代码（`neon.ts`）

除了以命令式方式创建分支（见上文 CLI / MCP / API）之外，你还可以在 neon.ts 中以声明式方式编写新分支的配置——这是 Neon 的基础设施即代码文件（完整参考请参阅 neon 技能）。branch 属性是一个函数，接收正在评估的分支并返回其设置，因此项目中创建的每个分支都有一致的生命周期和计算配置，无需为每个分支单独设置标志。

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // never reconcile existing branches
    if (branch.isDefault) return { protected: true };
    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
      return {
        parent: "main",
        ttl: "7d", // ephemeral: auto-expire 7 days after creation (max 30d)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // scale to zero
            autoscalingLimitMaxCu: 1, // keep throwaway branches cheap
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

闭包会接收目标分支的只读描述符——name、exists、isDefault、parentId 等——并返回要应用的调整项：parent、ttl（自动过期）、protected 和 postgres.computeSettings。这是对上述临时生命周期管理以及每个 PR / 每项测试模式的声明式补充：无需在每次执行 neon branches create 时都记得添加 --expires-at，TTL 和计算配置会保存在版本控制中，并应用于每个匹配的分支。

由于 neon checkout 会在创建分支时应用此策略，新建的 preview/* 或 dev-* 分支会自动设置过期时间并缩容至零。检出_已有_分支不会协调其配置——运行 neon deploy（neon config apply 的别名）即可将更改应用到已存在的分支。

在 CI/CD 中进行分支管理

Neon 分支的常见 CI/CD 用例：

**按 PR 创建预览部署：**PR 开启时创建分支，针对该分支部署预览，关闭时删除分支。每个 PR 都有独立的数据库分支。将分支的 DATABASE_URL 注入已部署应用的方式因托管服务提供商而异——请参阅 preview-branches-with-cloudflare、preview-branches-with-vercel 或 preview-branches-with-fly，了解经过验证的模式。
**在 CI 中测试迁移：**合并前，针对包含类似生产环境数据的分支运行有风险的架构更改。
**查看架构差异：**使用 schema-diff GitHub Action，自动在 PR 中评论数据库层的差异。

示例

示例 1：使用真实数据进行迁移测试

用户输入：“我需要针对类似生产环境的数据测试一项有风险的迁移。”

Agent 输出形式：

建议使用普通分支并解释原因。
分享文档链接：https://neon.com/docs/introduction/branching
先检查工具路径（使用 CLI 时运行 neon --version；只有 CLI 不可用时才使用 MCP）。
提供命令：
- neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
- neon connection-string migration-test

示例 2：敏感数据开发工作流

用户输入：“由于合规要求，我们不能复制生产环境数据。”