Originally published at https://beachone1155.vercel.app/blog/vercel-neon-branch-limit
問題の発覚
Vercelでプレビューデプロイを実行したところ、以下のエラーが発生しました：
engineer_blog_comments: Create database branch for deployment
Branch limit reached. Upgrade your plan or delete unused branches.
Neonの無料プランでは、データベースブランチが最大10個までという制限があり、それに達してしまったようです。
原因の調査
Vercel統合Neonの動作
VercelとNeonを統合すると、デフォルトで以下のような動作になります：
- Production環境（本番）: メインのデータベースブランチを使用
- Preview環境（プレビュー）: 各プレビューデプロイごとに新しいブランチを自動作成
つまり、PRを作成するたび、またはプレビューデプロイのたびに、Neon側で新しいデータベースブランチが作成されます。
なぜブランチが増えるのか
- 新しいPRを作成 → プレビューデプロイ実行
- Vercelが自動的にNeonブランチを生成（例:
preview/feature/r2e-frontend） - PRをマージしてもブランチは残る
- 新しいPRを複数作成 → ブランチが増え続ける
- 10個に達するとエラー
対処方法: 固定プレビューブランチを使用
すべてのプレビューデプロイで同じ固定ブランチを使用するように設定することで、新しいブランチが作成されなくなります。
設定手順
1. Neon Consoleで固定ブランチを作成
- Neon Consoleにアクセス
- プロジェクト「engineer_blog_comments」を選択
- 左サイドバーの「Branches」をクリック
- 「Create Branch」をクリック
- ブランチ名:
preview（任意の名前でOK） - 「Branch from」:
mainを選択 - 作成ボタンをクリック
2. 固定ブランチの接続文字列を取得
作成したブランチを選択し、Connection DetailsからPOSTGRES_URLをコピーします。
postgresql://user:pass@ep-xxx-pooler.region.neon.tech/neondb?sslmode=require
3. Vercel CLIで環境変数を設定
Preview環境とDevelopment環境に、固定ブランチのPOSTGRES_URLを設定します：
# Preview環境に設定
echo "固定ブランチのPOSTGRES_URL" | vercel env add POSTGRES_URL preview
# Development環境にも設定（ローカル開発用）
echo "固定ブランチのPOSTGRES_URL" | vercel env add POSTGRES_URL development
これにより：
- ✅ Production環境: 本番データベース（mainブランチ）を使用
- ✅ Preview環境: 固定プレビューブランチを使用（新しいブランチは作成されない）
- ✅ Development環境: 固定プレビューブランチを使用
設定の確認
環境変数が正しく設定されたか確認：
vercel env ls | grep POSTGRES_URL
出力例：
POSTGRES_URL Encrypted Development X ago
POSTGRES_URL Encrypted Preview X ago
重要: Production環境にはPOSTGRES_URLを設定しないことで、本番データベースが使用されます。
既存の未使用ブランチの削除
既に10個に達している場合は、未使用のブランチを削除する必要があります。
Neon Consoleでの削除手順
- Neon Console → プロジェクト「engineer_blog_comments」
- 「Branches」をクリック
- 未使用のプレビューブランチを確認（例:
preview/feature/*,preview/fix/*など） - 各ブランチの右側「...」メニューから「Delete」を選択
注意: mainブランチは削除しないでください。本番環境で使用されています。
推奨される運用
定期的なクリーンアップ
- マージ済みPRのプレビューブランチは定期的に削除
- アクティブなPRのブランチのみ保持
- ブランチ数が上限（9個）に近づいたら未使用ブランチを削除
スクリプト化（オプション）
削除手順をスクリプト化することも可能です：
# scripts/cleanup-neon-branches.sh
#!/bin/bash
# 未使用のNeonプレビューブランチを削除するためのスクリプト
# 使用法: Neon Console (https://console.neon.tech) で手動削除を行うか、
# Neon CLIを使用してブランチをリスト・削除します
set -e
echo "=========================================="
echo "Neonプレビューブランチ削除ガイド"
echo "=========================================="
echo ""
echo "このスクリプトは、Neon Consoleでのブランチ削除手順を案内します。"
echo ""
echo "手順:"
echo "1. https://console.neon.tech にアクセス"
echo "2. プロジェクト「engineer_blog_comments」を選択"
echo "3. 左サイドバーの「Branches」をクリック"
echo "4. 以下のブランチを削除（mainブランチは削除しない）:"
echo ""
echo " 削除対象（未使用のプレビューブランチ）:"
echo " - preview/feature/*"
echo " - preview/fix/*"
echo " - preview/chore/*"
echo " - その他の古いプレビューブランチ"
echo ""
echo "5. 各ブランチの右側にある「...」メニューから「Delete」を選択"
echo ""
echo "⚠️ 注意:"
echo " - mainブランチは削除しないでください"
echo " - 現在使用中のプレビューブランチは削除しないでください"
echo " - 削除後、新しいプレビューデプロイで新しいブランチが作成されます"
echo ""
echo "現在のNeonブランチ数が10/10の場合は、"
echo "上記の手順で削除してから新しいデプロイを行ってください。"
echo ""
まとめ
- 問題: Vercel統合Neonでプレビューデプロイごとに自動ブランチが作成され、無料プランの上限（10個）に達した
- 解決: 固定プレビューブランチを使用する設定で、新しいブランチの作成を防止
-
設定: Vercel CLIでPreview環境に固定ブランチの
POSTGRES_URLを設定 - 運用: 未使用ブランチを定期的にクリーンアップ
これで、プレビューデプロイ時に新しいブランチが作成されなくなり、ブランチ数の上限問題を回避できます。