neon-postgres-branches

Name: neon-postgres-branches
Author: neondatabase

github.com/neondatabaseデータ・データベース10732.6k 回インストール1 日前に更新

リポジトリ

neon-postgres-branches について

開発やマイグレーション向けに、Neon の Postgres ブランチを作成・管理するスキルです。データ付きとスキーマのみのブランチを選び、CLI を優先しつつ MCP と API も代替手段として扱います。

主な機能

01通常ブランチとスキーマのみを選択
02Neon CLI または MCP でブランチ作成
03親から子ブランチをリセット
04neon.ts でブランチのライフサイクルを設定
05CI とプレビューのワークフローで利用

活用シーン

01本番に近いデータでマイグレーションを検証
02機密行データを複製せずに開発
03親ブランチからステージング環境を更新
04プルリクエスト用の独立した DB ブランチを作成

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）でブランチを作成します。

実データを使って、現実的なマイグレーションやクエリのテストを行うには、通常のブランチを使用します。
機密データをコピーせずに構造だけが必要なワークフローには、**スキーマのみのブランチ（ベータ）**を使用します。

ブランチの種類を選択する

まず、次の判断基準を使用してください。

ユーザーが本番環境に近いデータを使って、複雑なマイグレーション、パフォーマンス、または動作をテストしたい場合は、通常のブランチを選択します。
機密データのコピーを避ける必要がある場合は、スキーマのみのブランチを選択します。

依頼が曖昧な場合は、次の確認を一つだけ行ってください。「テストには現実的なデータが必要ですか。それとも、データが機密であるため、スキーマ構造だけが必要ですか？」

ツールの選択：CLI または MCP

Neon CLI と Neon MCP サーバーの両方をサポートしますが、既定では CLI を使用してください。MCP は、CLI が環境で利用できない、またはブロックされている、認証できない場合、もしくはユーザーが明示的に 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>
```

スキーマのみのブランチを作成する（ベータ、機密データ向け）

本番環境の行データをテスト用ブランチにコピーしてはならない場合に使用してください。

リンク：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

ベータ版のサポートに関するガイダンス（必須）

スキーマのみのブランチ機能はベータ版です。ユーザーから予期しない動作、エラー、機能の不足について報告があった場合：

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 を指定すると、リセット前の状態がロールバック用のバックアップブランチとして保持されますが、後でクリーンアップするブランチが1つ増えます。

--project-id の繰り返しを避けるための、任意のコンテキスト設定：

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

Console と API の使用方法

Console： 対象の子ブランチを開き、Actions から Reset from parent を選択します。
API： ブランチの restore エンドポイントを使用し、source_branch_id に親ブランチ ID を設定します。

注意事項と留意点

スキーマのみのブランチは、構造のみのクローン作成や、機微データおよびコンプライアンスに関するデータ管理のためのものです。
スキーマのみのブランチは独立したルートブランチ（親ブランチがなく、履歴も共有されない）であるため、親ブランチからのリセットは適用されません。
実際の行の形状、データ量、エッジケースに依存するマイグレーションテストでは、通常のブランチを優先してください。
ルートブランチの上限やブランチごとのストレージ上限により、ユーザーが作成できるスキーマのみのブランチ数が制限される場合があります。
ユーザーが判断に迷っている場合は、次の選択を基本として推奨してください：
- マイグレーションの検証には 通常のブランチ。
- コンプライアンスやプライバシー上の制約には スキーマのみのブランチ。

便利なワークフローパターン

ユーザーが単一のコマンドではなくプロセスの推奨を求めている場合は、次の方法を提案してください：

PR ごとに1つのブランチ： PR のオープン時にブランチを作成し、マージまたはクローズ時に削除して、マイグレーションテストを分離します。
テスト実行ごとに1つのブランチ： パイプラインの開始時にブランチを作成し、マイグレーションとテストを実行して、終了時に削除することで、決定論的な CI を実現します。
開発者ごとに1つのブランチ： 本番環境に近い形状の分離された開発環境を用意し、共有テストデータでチーム内の競合が起きないようにします。
PII を考慮したブランチ運用： 本番環境に機微データがある場合は、匿名化されたブランチから開発用／PR 用ブランチを作成するか、スキーマのみのブランチを使用します。
一時ブランチのライフサイクル管理： ブランチの有効期限を設定し、クリーンアップを自動化して、古いブランチによる不要なストレージや履歴のコストが蓄積しないようにします。

作成後の環境更新プロンプト

ブランチ作成後、新しいブランチを指すようにローカル環境の認証情報を更新するかどうか、ユーザーに確認してください。

質問：「.env の DATABASE_URL を、この新しいブランチの接続文字列に更新しますか？」
はいの場合は、新しいブランチの接続文字列を、指定された環境ファイル／キーに書き込みます。
いいえの場合は、認証情報を変更せず、手動で使用できるよう接続文字列を共有します。
明示的な確認なしに、既存の環境キーを上書きしないでください。

Neon Infrastructure as Code (`neon.ts`)

ブランチを命令型で作成する（上記の CLI／MCP／API）だけでなく、Neon の Infrastructure as Code ファイルである neon.ts で、新しいブランチが受け取る設定を宣言的にプログラムできます（詳細については 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 のクローズ時に削除します。各 PR に分離されたデータベースブランチが用意されます。ブランチの DATABASE_URL をデプロイ済みアプリに設定する方法はホスティングプロバイダーによって異なります。動作確認済みのパターンについては、preview-branches-with-cloudflare、preview-branches-with-vercel、または preview-branches-with-fly を参照してください。
CI でのマイグレーションテスト： マージ前に、本番環境に近いデータを含むブランチに対して、リスクの高いスキーマ変更を実行します。
スキーマ差分の可視化： schema-diff GitHub Action を使用して、PR に DB レイヤーの差分を自動コメントします。

例

例 1：現実的なデータを使ったマイグレーションテスト

ユーザー入力：「本番環境に近いデータを使って、リスクの高いマイグレーションをテストしたいです。」

エージェントの出力形式：

通常のブランチを推奨し、その理由を説明します。
ドキュメントへのリンクを共有します：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：機微データを扱う開発ワークフロー

ユーザー入力：「コンプライアンス上、本番データをコピーできません。」