neondatabase/neon-postgres-branches

最初に: Neonの概要、Neonの始め方、Neon開発のベストプラクティスなどについては、親スキルである neon を使用してください。

もし neon スキルがインストールされていない場合は、https://neon.com/docs/ai/skills/neon/SKILL.md から取得するか、以下のコマンドでインストールしてください:

npx skills add neondatabase/agent-skills --skill neon

Lakebase Postgres ブランチング

成果物: 作成されたNeonブランチ、または作成が進められない場合の明確で実行可能な次のステップ。適切なブランチタイプを選択し、CLI（またはCLIが使用できない場合はMCP）を使用してブランチ作成を実行します。

• 通常ブランチ: 実際の移行とクエリテストを現実的なデータで行う場合。
• スキーマのみブランチ（ベータ）: 行をコピーせずに構造のみが必要な、機密データを扱うワークフロー向け。

ブランチタイプの決定

以下の決定ルールを最初に使用します:

1. ユーザーが複雑な移行、パフォーマンス、または本番に近いデータに対する動作をテストしたい場合は、通常ブランチを選択します。
2. ユーザーが機密データのコピーを避ける必要がある場合は、スキーマのみブランチを選択します。

リクエストがあいまいな場合は、1つ明確な質問をします: 「テストのために現実的なデータが必要ですか、それともデータが機密であるためスキーマ構造のみ必要ですか？」

ツールの選択: 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

選択順序

1. まずCLIを確認します:
   • neon --version を実行してCLIがインストールされているか確認します。
   • neon projects list を実行して認証/コンテキストを確認します。
2. CLIがない場合は、クイックスタートで直接インストールを案内します。
3. CLIはインストールされているが認証されていない場合は、neon auth（またはAPIキー認証）を通じてユーザーをガイドし、その後続行します。
4. CLIが使用できない場合（環境へのCLIアクセスがない、実行がブロックされている、認証が不可能）、またはユーザーが明示的にMCPを要求した場合にMCPに切り替えます。Neon MCPツールが利用可能で認証されていることを確認し（例：プロジェクトの一覧表示が機能する）、その後以下のMCPブランチフローに従います。
5. どちらのパスも成功しない場合は、Neon REST APIを使用します:
   • https://neon.com/docs/guides/branching-neon-api.md

MCP ブランチフロー

1. データの機密性と移行テストの目標に基づいて、通常ブランチとスキーマのみブランチを選択します。
2. ブランチツール（例：create_branch）を使用してブランチを作成します。
3. 読み取りツール（例：describe_branch）で検証します。
4. 移行ワークフローの場合は、メインに適用する前にブランチベースの移行フローを優先します。

通常ブランチの作成（本番データ移行テストに推奨）

ユーザーが現実的なテスト条件を必要とする場合に使用します。 実際の本番に近いデータは、シードデータやデータ移行スクリプトが見逃す可能性のあるエッジケースを露呈する可能性があり、本番稼働前に移行の問題を発見するのに役立ちます。

リンク: https://neon.com/docs/introduction/branching.md

手順

1. まずツールパスを確定します（選択順序を参照）: neon --version でCLIを確認し、CLIが使用できない場合のみMCPにフォールバックします。

2. プロジェクトコンテキストが設定されていることを確認するか（neon set-context --project-id <your-project-id>）、コマンドに --project-id を含めます。

3. ブランチを作成します:

   neon branches create \
     --name <ブランチ名> \
     --parent <親ブランチIDまたは名前> \
     --expires-at 2026-12-15T18:02:16Z
   

4. 新しいブランチの接続文字列をオプションで取得します:

   neon connection-string <ブランチ名>
   

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

本番の行をテストブランチにコピーしてはいけない場合に使用します。

リンク: https://neon.com/docs/guides/branching-schema-only.md

手順

1. まずツールパスを確定します（選択順序を参照）: neon --version でCLIを確認し、CLIが使用できない場合のみMCPにフォールバックします。

2. スキーマのみブランチを作成します:

   neon branches create \
     --name <スキーマのみブランチ名> \
     --parent <親ブランチIDまたは名前> \
     --schema-only \
     --expires-at 2026-12-15T18:02:16Z
   

   複数のプロジェクトが存在する場合は、--project-id を含めます:

   neon branches create \
     --name <スキーマのみブランチ名> \
     --parent <親ブランチIDまたは名前> \
     --schema-only \
     --project-id <あなたのプロジェクトID> \
     --expires-at 2026-12-15T18:02:16Z
   

ベータサポートガイダンス（必須）

スキーマのみブランチはベータ版です。ユーザーが予期しない動作、エラー、または不足している機能を報告した場合:

1. Neonコンソールでフィードバックを共有するよう依頼してください:
   • https://console.neon.tech/app/projects?modal=feedback
2. Neon Discordでサポート会話を開くことを推奨します:
   • https://discord.gg/92vNTzKDGp

親からのリセット

子ブランチが最新の状態からずれており、ユーザーが親ブランチの最新のスキーマとデータでクリーンなリフレッシュを希望する場合に使用します。

リンク: https://neon.com/docs/guides/reset-from-parent.md

機能

• 子ブランチのスキーマとデータを親の最新状態に完全に置き換えます。
• マージは行いません。子ブランチのローカル変更は失われます。
• 同じ接続詳細は維持されますが、リセット中にアクティブな接続が一時的に中断されます。

推奨するタイミング

• 開発ブランチまたはステージングブランチが本番から大きく遅れている場合。
• ユーザーが親と同期したクリーンな状態から新しい機能を開始したい場合。
• チームが一貫したテストベースラインのためにステージングを本番からリフレッシュしたい場合。

ハード制約とブロッカー

• 子ブランチのみリセットできます（ルートブランチとスキーマのみのルートブランチは親からリセットできません）。
• 対象ブランチに子ブランチがある場合、それらの子ブランチが削除されるまでリセットはブロックされます。
• 親ブランチがスナップショットから復元された後、最大24時間は親からのリセットが利用できない場合があります。
• 親からのリセットは常に現在の親の状態を使用します。特定の時点への復元が必要な場合は、Instant Restoreを使用してください。

CLI の使用法

neon branches reset <id|name> --parent --preserve-under-name <バックアップブランチ名>

プロジェクトコンテキストがまだ設定されていない場合は、プロジェクトIDを含めます:

neon branches reset <id|name> --parent --preserve-under-name <バックアップブランチ名> --project-id <プロジェクトID>

--preserve-under-name は、ロールバック用のバックアップブランチとしてリセット前の状態を保持しますが、後でクリーンアップするための余分なブランチが1つ追加されます。

--project-id を繰り返さないようにするためのオプションのコンテキスト設定:

neon set-context --project-id <プロジェクトID>

コンソールとAPIの使用法

• コンソール: 対象の子ブランチを開き、アクションから親からリセットを選択します。
• API: ブランチのリストアエンドポイントを使用し、source_branch_id を親ブランチIDに設定します。

注意事項と注意点

• スキーマのみブランチは、構造のみのクローンと機密/準拠データ制御のためのものです。
• スキーマのみブランチは独立したルートブランチであるため（親ブランチや共有履歴がありません）、親からのリセットは適用されません。
• 実際の行の形状、ボリューム、エッジケースに依存する移行テストには、通常ブランチを推奨します。
• ルートブランチの許容数とブランチごとのストレージ制限により、ユーザーが作成できるスキーマのみブランチの数が制限される場合があります。
• ユーザーが不明な場合のデフォルトの推奨:
  • 通常ブランチ: 移行の検証用。
  • スキーマのみブランチ: コンプライアンスとプライバシー制約用。

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

ユーザーが（単一のコマンドだけでなく）プロセスの推奨を求めてきた場合は、以下を提案してください:

• PRごとに1ブランチ: PRが開かれたらブランチを作成し、マージまたはクローズされたら削除し、移行テストを分離します。
• テスト実行ごとに1ブランチ: パイプラインの開始時にブランチを作成し、移行/テストを実行し、終了時に削除して決定論的なCIを実現します。
• 開発者ごとに1ブランチ: 本番に近い形状の分離された開発環境。共有テストデータでのチームの衝突を回避します。
• PIIを意識したブランチング: 本番データに機密データが含まれる場合は、匿名化されたブランチから開発/PRブランチを派生させるか、スキーマのみブランチを使用します。
• 一時的なライフサイクル管理: ブランチの有効期限を設定し、クリーンアップを自動化して、古いブランチが回避可能なストレージ/履歴コストを蓄積しないようにします。

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

ブランチ作成後、ローカル環境の認証情報を新しいブランチに更新するかどうかをユーザーに尋ねます。

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

Neon Infrastructure as Code (neon.ts)

上記の命令的なブランチ作成（CLI / MCP / API）に加えて、neon.ts で新しいブランチが受信する設定を宣言的にプログラムできます。これはNeonのInfrastructure as Codeファイルです（完全なリファレンスは neon スキルを参照）。branch プロパティは、評価対象のブランチの関数で、その設定を返します。これにより、プロジェクトから生成されるすべてのブランチが、ブランチごとのフラグなしで一貫したライフサイクルとコンピュートプロファイルを取得します。

npm i @neon/config

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

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // 既存のブランチは決して調整しない
    if (branch.isDefault) return { protected: true };
    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
      return {
        parent: "main",
        ttl: "7d", // 一時的: 作成から7日後に自動期限切れ（最大30日）
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // ゼロにスケール
            autoscalingLimitMaxCu: 1, // 使い捨てブランチは安価に保つ
            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: 現実的なデータを用いた移行テスト

ユーザー入力: 「リスクのある移行を本番に近いデータでテストする必要があります。」

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

1. 通常ブランチを推奨し、その理由を説明します。
2. ドキュメントリンクを共有します: https://neon.com/docs/introduction/branching
3. 最初にツールパスを確認します（CLIは neon --version、MCPはCLIが使用できない場合のみ）。
4. コマンドを提供します:
   • neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
   • neon connection-string migration-test

例2: 機密データ開発ワークフロー

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

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

1. スキーマのみブランチを推奨し、その理由を説明します。
2. ドキュメントリンクを共有します: https://neon.com/docs/guides/branching-schema-only
3. 最初にツールパスを確認します（CLIは neon --version、MCPはCLIが使用できない場合のみ）。
4. コマンドを提供します:
   • neon branches create --name compliance-dev --parent main --schema-only --project-id <あなたのプロジェクトID> --expires-at 2026-12-15T18:02:16Z
5. ベータサポートパスに言及します:
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

参考文献

• https://neon.com/docs/guides/branch-expiration.md
• https://neon.com/docs/guides/neon-github-integration.md
• https://neon.com/docs/ai/neon-mcp-server.md
• https://neon.com/branching