結論：timeoutを延ばす前に、DBがない時の業務境界を決める
Claude Code 2.1.274では、Claude Apps Gatewayの設定にstore.connect_timeout_secondsが追加され、Postgresへの接続待ち時間を延ばせます。公式changelogの既定値は5秒です。DBが数秒遅れて起動する環境では有効ですが、到達不能や認証失敗を長く待つ設定ではありません。timeout、再試行、エラー表示、トラフィック停止の四つを一組で決めてください。
読者の課題は、Gatewayのbootが止まった時に、Postgresの一時的な起動遅延なのか、URL・TLS・credentialの設定ミスなのかを切り分けられないことです。待ち時間だけを増やすと、障害が見えにくくなり、認証状態やrate limitの保存が不確かなままリクエストを受ける危険があります。
根拠はClaude Code v2.1.274公式リリースとClaude Code公式changelogです。Gatewayの構成、PostgreSQL 14以上、OIDC、private network、起動手順はClaude Apps Gateway公式文書を正本にします。既存のOTLP collector設計は観測経路、費用上限は支出停止、料金表示は請求照合が中心で、本稿はboot時のDB接続境界に限定します。
5秒の既定値と延長を比較する
| 状態 | 判断 | 記録する証拠 |
|---|---|---|
| DBが数秒遅れて起動 | 上限を延ばし、限定回数で再試行 | 接続開始・成功時刻 |
| DNS・network不可 | 待たずに停止し経路を修正 | 名前解決・route・security group |
| 認証・TLS失敗 | credentialとsslmodeを確認 | secret version・server error |
| DB負荷・pool枯渇 | 容量と接続数を確認 | Postgres metrics・active sessions |
| 接続後のDB断 | in-flightと新規受付を分ける | request数・再接続履歴 |
Gatewayは認証のdevice flowやrate-limit countersなど、DBに依存する状態を持ちます。公式文書にあるPostgreSQL 14以上、TLS推奨、バックアップ対象を前提に、接続待ちを「ただのヘルスチェック」と扱わないでください。起動を通すことより、DBがない時に何を保存できず、何を受け付けないかを決めることが重要です。
安全に設定する8手順
- 依存関係を書く。sign-in、rate limit、spend、audit、identityのうち、どれがDBを必要とするかを表にします。
- 既定値で実測する。まず5秒を基準に、DBがcold startする時の接続時間とboot結果を記録します。
- 接続経路を確認する。GatewayからPostgresまでのDNS、private network、security group、TLSを別々に確認します。
- credentialを照合する。secret version、user、database、sslmodeをreadbackし、ログへパスワードを出しません。
- 延長幅を決める。DBの起動遅延にだけ合わせ、無限待ちにせず、業務のSLOと運用者の検知時間を超えない値にします。
- 再試行を制限する。短い間隔で何度も接続してDBをさらに圧迫しないよう、回数、backoff、終了条件を固定します。
- 障害表示を確認する。2.1.274の改善に沿って、
store.postgres_urlと設定timeoutを手掛かりに調査できるエラーをreadbackします。 - 受付境界を試す。DB停止中にlogin、inference、spend check、health checkがどう応答するかを検証し、fail-openを安易に採用しません。
設定ファイルの変更は、接続待ちだけの差分としてreviewします。Postgres URL、credentials、upstream model、IdP、listen設定を同じ変更で動かすと、原因が分かりません。まず検証環境でDBを意図的に数秒遅らせ、接続成功、timeout、retry上限、ログ、監視通知を一つずつ確認してください。
本番でtimeoutを延ばす場合は、延長前のboot時間と、延長後に許容する停止時間を比較します。長く待つ間にロードバランサーがhealth checkを落とす、orchestratorがpodを再起動する、同じDBへ接続が集中することがあります。アプリのtimeoutだけでなく、ingress、health check、container、databaseのtimeoutを一覧にして、最短の上限がどこかを確認します。
設定の妥当性は、正常起動だけでなく「DBがあとから復旧する」「復旧しない」「接続後に切断する」の三条件で確認します。各条件でGatewayが出すエラー、監視の通知、利用者への表示、運用者の次の操作を記録します。特に自動再起動がある環境では、timeout延長が再起動の連鎖を増やさないかを見て、接続poolと同時起動数も合わせて制限してください。
障害対応チェックリスト
- Claude CodeとGatewayのversionを記録した
- PostgreSQLのversionと接続先を確認した
- 既定の5秒でcold startを測った
store.connect_timeout_secondsの変更理由と期限を書いた- 再試行回数、backoff、停止条件を決めた
- URL・TLS・credentialエラーを区別した
- DBなしで受け付ける操作と拒否する操作を決めた
- 復旧後のin-flightと新規requestを確認した
接続が復旧しただけで完了にしないでください。停止中に失敗したlogin、作成されなかったaudit、重複したretry、超過したrate-limitがないかを照合します。DBへ接続できなかった時間、影響したrequest、担当者の判断、設定を戻したかをインシデント記録へ残すと、次回のtimeout設計を改善できます。
よくある質問
5秒は必ず変更すべきですか？
変更必須ではありません。まず5秒を基準に実測し、DBの通常起動時間、orchestrator、SLOが示す必要性がある場合だけ延長します。
Postgres URLをログに出してよいですか？
接続先の情報が内部構成やcredentialを含む場合があります。公式のエラー手掛かりを使いつつ、パスワードやtokenはマスキングし、閲覧権限を限定してください。
DB障害時にupstreamへ直接fallbackできますか？
認証・rate limit・auditの保存要件を回避するため、安易なfallbackは危険です。データ整合性と責任者の承認を確認した上で、限定的なread-only経路にします。
公式情報
次の一歩
Gatewayのtimeoutだけでなく、認証、監査、費用、停止責任までつながっていない場合は、障害時の判断が属人化します。Miraigentの無料診断で、構成と復旧手順を業務単位で棚卸しできます。