Back to Details

neon-postgres-branches

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Neon Postgres Branching

Neon Postgres 分支

The outcome of this skill should be a created Neon branch (or a clear, actionable next step if creation cannot proceed). Choose the correct branch type, then execute branch creation via MCP or CLI.
  • Normal branch for realistic migration and query testing with real data.
  • Schema-only branch (Beta) for sensitive data workflows where structure is needed without copying rows.
本技能的目标是创建一个Neon分支（若无法创建则提供清晰可执行的下一步操作）。选择正确的分支类型，然后通过MCP或CLI执行分支创建。
  • 普通分支：用于使用真实数据进行真实场景的迁移和查询测试。
  • 仅架构分支（测试版）：适用于需要结构但无需复制数据行的敏感数据工作流。

Branch Type Decision

分支类型决策

Use this decision rule first:
  1. If the user wants to test complex migrations, performance, or behavior against production-like data, choose a normal branch.
  2. If the user needs to avoid copying sensitive data, choose a schema-only branch.
If the request is ambiguous, ask one clarifying question: "Do you need realistic data for testing, or only schema structure because the data is sensitive?"
请先遵循以下决策规则：
  1. 如果用户需要针对类生产数据测试复杂迁移、性能或行为，请选择普通分支。
  2. 如果用户需要避免复制敏感数据，请选择仅架构分支。
若请求不明确，请提出一个澄清问题： “您测试时需要真实数据，还是因数据敏感仅需架构结构？”

Tool Selection: CLI or MCP

工具选择：CLI 或 MCP

Always support both Neon CLI and Neon MCP server. Prefer the tool the user already has installed and authenticated.
MCP link: https://neon.com/docs/ai/neon-mcp-server.md CLI link: https://neon.com/docs/reference/cli-quickstart
始终支持Neon CLI和Neon MCP服务器。优先选择用户已安装并完成认证的工具。
MCP链接：https://neon.com/docs/ai/neon-mcp-server.md CLI链接：https://neon.com/docs/reference/cli-quickstart

Selection order

选择顺序

  1. Check MCP first in MCP-enabled environments:
    • If Neon MCP tools are available and authenticated (for example, listing projects works), use MCP.
  2. If MCP is unavailable or not authenticated, check CLI:
    • Run 
      neonctl --version
      to confirm CLI is installed.
    • Run 
      neonctl projects list
      to confirm auth/context.
  3. If CLI is missing, direct installation via quickstart.
  4. If CLI is installed but not authenticated, guide the user through 
    neonctl auth
    (or API key auth), then continue.
  5. If both MCP and CLI paths are unsuccessful, use the Neon REST API:
  1. 先在支持MCP的环境中检查MCP：
    • 若Neon MCP工具可用且已完成认证（例如，项目列表可正常显示），则使用MCP。
  2. 若MCP不可用或未完成认证，则检查CLI：
    • 运行 
      neonctl --version
      确认CLI已安装。
    • 运行 
      neonctl projects list
      确认认证/上下文状态。
  3. 若CLI未安装，引导用户通过快速入门指南进行安装。
  4. 若CLI已安装但未认证，引导用户执行 
    neonctl auth
    （或API密钥认证），然后继续操作。
  5. 若MCP和CLI均无法使用，则使用Neon REST API：

MCP branch flow

MCP分支流程

  1. Choose normal vs schema-only based on data sensitivity and migration-testing goals.
  2. Use branch tools (for example, 
    create_branch
    ) to create the branch.
  3. Validate with read tools (for example, 
    describe_branch
    ).
  4. For migration workflows, prefer branch-based migration flows before applying to main.
  1. 根据数据敏感性和迁移测试目标选择普通分支或仅架构分支。
  2. 使用分支工具（例如 
    create_branch
    ）创建分支。
  3. 使用读取工具（例如 
    describe_branch
    ）验证分支。
  4. 对于迁移工作流，优先采用基于分支的迁移流程，再应用到主分支。

Create a Normal Branch (Preferred for Real-Data Migration Testing)

创建普通分支（推荐用于真实数据迁移测试）

Use this when the user needs realistic testing conditions. Real production-like data can expose edge cases your seed or data migration scripts miss, which helps catch migration issues before going live.
Link: https://neon.com/docs/introduction/branching.md
当用户需要真实测试环境时使用此分支类型。 类生产的真实数据可以暴露种子数据或迁移脚本未覆盖的边缘情况，有助于在上线前发现迁移问题。
链接：https://neon.com/docs/introduction/branching.md

Steps

步骤

  1. Use MCP if already available/authenticated; otherwise verify CLI with 
    neonctl --version
    .
  2. Ensure project context is set (
    neonctl set-context --project-id <your-project-id>
    ) or include 
    --project-id
    on commands.
  3. Create branch:
bash
neonctl branches create \
  --name <branch-name> \
  --parent <parent-branch-id-or-name> \
  --expires-at 2026-12-15T18:02:16Z
  1. Optionally fetch a connection string for the new branch:
bash
neonctl connection-string <branch-name>
  1. 若MCP已可用/已认证则使用MCP；否则通过 
    neonctl --version
    验证CLI。
  2. 确保已设置项目上下文（
    neonctl set-context --project-id <your-project-id>
    ），或在命令中包含 
    --project-id
    参数。
  3. 创建分支：
bash
neonctl branches create \
  --name <branch-name> \
  --parent <parent-branch-id-or-name> \
  --expires-at 2026-12-15T18:02:16Z
  1. 可选：获取新分支的连接字符串：
bash
neonctl connection-string <branch-name>

Create a Schema-Only Branch (Beta, Sensitive Data)

创建仅架构分支（测试版，适用于敏感数据）

Use this when users must not copy production rows into the test branch.
Link: https://neon.com/docs/guides/branching-schema-only.md
当用户不得将生产数据行复制到测试分支时使用此分支类型。
链接：https://neon.com/docs/guides/branching-schema-only.md

Steps

步骤

  1. Use MCP if already available/authenticated; otherwise verify CLI with 
    neonctl --version
    .
  2. Create schema-only branch:
bash
neonctl branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --expires-at 2026-12-15T18:02:16Z
If multiple projects exist, include:
bash
neonctl 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
  1. 若MCP已可用/已认证则使用MCP；否则通过 
    neonctl --version
    验证CLI。
  2. 创建仅架构分支：
bash
neonctl branches create \
  --name <schema-only-branch-name> \
  --parent <parent-branch-id-or-name> \
  --schema-only \
  --expires-at 2026-12-15T18:02:16Z
若存在多个项目，需添加以下参数：
bash
neonctl 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 Support Guidance (Mandatory)

测试版支持指南（必填）

Schema-only branching is in Beta. If users report unexpected behavior, errors, or missing capabilities:
  1. Ask them to share feedback in the Neon Console:
  2. Recommend opening a support conversation in the Neon Discord:
仅架构分支处于测试阶段。若用户反馈异常行为、错误或功能缺失：
  1. 请他们在Neon控制台提交反馈：
  2. 建议他们在Neon Discord中发起支持对话：

Reset from parent

从父分支重置

Use this when a child branch has drifted and the user wants a clean refresh from the parent branch's latest schema and data.
Link: https://neon.com/docs/guides/reset-from-parent.md
当子分支已偏离父分支状态，用户希望从父分支的最新架构和数据刷新出干净的分支时使用此功能。
链接：https://neon.com/docs/guides/reset-from-parent.md

What it does

功能说明

  • Fully replaces the child branch schema and data with the parent's latest state.
  • Does not merge; local changes on the child branch are lost.
  • Keeps the same connection details, but active connections are briefly interrupted during reset.
  • 用父分支的最新状态完全替换子分支的架构和数据。
  • 此操作不涉及合并；子分支上的本地更改将丢失。
  • 保留原连接信息，但重置期间活动连接会短暂中断。

When to recommend it

推荐使用场景

  • Development or staging branch is too far behind production.
  • User wants to start a new feature from a clean parent-aligned state.
  • Team wants to refresh staging from production for consistent testing baselines.
  • 开发或 staging 分支与生产环境差距过大。
  • 用户希望从与父分支对齐的干净状态开始开发新功能。
  • 团队希望从生产环境刷新staging环境，以获得一致的测试基准。

Hard constraints and blockers

硬性限制与阻塞情况

  • Only child branches can be reset (root branches and schema-only root branches cannot be reset from parent).
  • If the target branch has children, reset is blocked until those child branches are removed.
  • After a parent branch is restored from snapshot, reset-from-parent may be unavailable for up to 24 hours.
  • Reset-from-parent always uses the current parent state; use Instant restore for point-in-time recovery needs.
  • 仅子分支可被重置（根分支和仅架构根分支无法从父分支重置）。
  • 若目标分支存在子分支，需先删除这些子分支才能执行重置。
  • 父分支从快照恢复后，“从父分支重置”功能可能在24小时内无法使用。
  • “从父分支重置”始终使用父分支的当前状态；若需时间点恢复，请使用即时恢复功能。

CLI usage

CLI使用方式

bash
neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
If project context is not already set, include project ID:
bash
neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
--preserve-under-name
keeps the pre-reset state as a backup branch for rollback, but adds one extra branch to clean up later.
Optional context setup to avoid repeating 
--project-id
:
bash
neonctl set-context --project-id <project-id>
bash
neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
若未设置项目上下文，需添加项目ID：
bash
neonctl branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
--preserve-under-name
参数会将重置前的状态保留为备份分支以便回滚，但后续需清理这个额外的分支。
可选：设置上下文以避免重复输入 
--project-id
：
bash
neonctl set-context --project-id <project-id>

Console and API usage

控制台与API使用方式

  • Console: Open the target child branch, then select Reset from parent from Actions.
  • API: Use the restore endpoint for the branch and set 
    source_branch_id
    to the parent branch ID.
  • 控制台：打开目标子分支，然后从“操作”中选择“从父分支重置”。
  • API：使用分支的恢复端点，并将 
    source_branch_id
    设置为父分支ID。

Notes and Caveats

注意事项

  • Schema-only branches are for structure-only cloning and sensitive/compliant data controls.
  • Schema-only branches are independent root branches (no parent branch and no shared history), so reset-from-parent does not apply.
  • For migration testing that depends on real-world row shapes, volumes, and edge cases, prefer normal branches.
  • Root branch allowances and per-branch storage limits can cap how many schema-only branches users can create.
  • If a user is unsure, default recommendation is:
    • Normal branch for migration validation.
    • Schema-only branch for compliance and privacy constraints.
  • 仅架构分支用于仅克隆结构的场景，以及敏感数据合规管控。
  • 仅架构分支是独立的根分支（无父分支且无共享历史），因此“从父分支重置”功能不适用。
  • 对于依赖真实数据行结构、数据量和边缘情况的迁移测试，优先选择普通分支。
  • 根分支配额和单分支存储限制可能会限制用户可创建的仅架构分支数量。
  • 若用户不确定，默认推荐：
    • 普通分支：用于迁移验证。
    • 仅架构分支：用于合规和隐私约束场景。

Useful Workflow Patterns

实用工作流模式

If the user asks for process recommendations (not just a single command), suggest these:
  • One branch per PR: Create branch when PR opens, delete when merged/closed, keep migration tests isolated.
  • One branch per test run: Create branch at pipeline start, run migrations/tests, delete at end for deterministic CI.
  • One branch per developer: Isolated dev environments with production-like shape; avoid team collisions on shared test data.
  • PII-aware branching: If production has sensitive data, derive dev/PR branches from an anonymized branch or use schema-only branches.
  • Ephemeral lifecycle hygiene: Set branch expiration and automate cleanup so old branches do not accumulate avoidable storage/history cost.
若用户询问流程建议（而非单一命令），可推荐以下模式：
  • 每个PR对应一个分支：PR创建时创建分支，合并/关闭时删除分支，保持迁移测试隔离。
  • 每次测试运行对应一个分支：流水线启动时创建分支，运行迁移/测试，结束时删除分支，实现确定性CI。
  • 每个开发者对应一个分支：提供类生产结构的隔离开发环境，避免团队在共享测试数据上的冲突。
  • PII感知分支：若生产环境包含敏感数据，从匿名化分支衍生开发/PR分支，或使用仅架构分支。
  • 临时分支生命周期管理：设置分支过期时间并自动清理，避免旧分支累积不必要的存储/历史成本。

Post-creation environment update prompt

创建后环境更新提示

After branch creation, ask whether the user wants to update local environment credentials to point at the new branch.
  • Ask: "Do you want me to update your 
    .env
    DATABASE_URL
    to this new branch connection string?"
  • If yes, write the new branch connection string to the requested env file/key.
  • If no, leave credentials unchanged and share the connection string for manual use.
  • Never overwrite an existing env key without explicit confirmation.
分支创建完成后，询问用户是否需要更新本地环境凭据以指向新分支。
  • 询问：“是否需要我将您的 
    .env
    文件中的 
    DATABASE_URL
    更新为这个新分支的连接字符串？”
  • 若用户同意，将新分支的连接字符串写入指定的环境文件/密钥。
  • 若用户拒绝，保持凭据不变并分享连接字符串供手动使用。
  • 未经明确确认，不得覆盖现有环境密钥。

Examples

示例

Example 1: Migration testing with realistic data

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

User input: "I need to test a risky migration against production-like data."
Agent output shape:
  1. Recommend a normal branch and explain why.
  2. Share docs link: https://neon.com/docs/introduction/branching
  3. Check the available/authenticated tool path first (MCP, otherwise CLI with 
    neonctl --version
    ).
  4. Provide commands: 
    • neonctl branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
    • neonctl connection-string migration-test
用户输入：“我需要针对类生产数据测试一个高风险的迁移。”
Agent输出格式：
  1. 推荐普通分支并说明原因。
  2. 分享文档链接：https://neon.com/docs/introduction/branching
  3. 优先检查可用/已认证的工具路径（MCP，否则通过 
    neonctl --version
    检查CLI）。
  4. 提供命令： 
    • neonctl branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
    • neonctl connection-string migration-test

Example 2: Sensitive data development workflow

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

User input: "We cannot copy production data because of compliance."
Agent output shape:
  1. Recommend schema-only branch and explain why.
  2. Share docs link: https://neon.com/docs/guides/branching-schema-only
  3. Check the available/authenticated tool path first (MCP, otherwise CLI with 
    neonctl --version
    ).
  4. Provide command: 
    • neonctl branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
  5. Mention Beta support path:
用户输入：“出于合规要求，我们不能复制生产数据。”
Agent输出格式：
  1. 推荐仅架构分支并说明原因。
  2. 分享文档链接：https://neon.com/docs/guides/branching-schema-only
  3. 优先检查可用/已认证的工具路径（MCP，否则通过 
    neonctl --version
    检查CLI）。
  4. 提供命令： 
    • neonctl branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
  5. 提及测试版支持渠道：

Further reading

扩展阅读