同時稼働するコンテナ向けに Immich のデータベース接続を最適化する方法
max_connectionsを最初に増やすのではなく、Immichのすべてのプロセスとその他のPostgreSQLクライアント全体で必要となるセッション数を測定して、Immichのデータベース接続を最適化します。データベースには、実際のワークロードに加えて管理用の余裕を確保するのに十分なセッションが必要ですが、同時実行数が過剰になると、クエリが高速化しないままメモリ使用量や競合が増加する可能性があります。
複数のコンテナを稼働させるホームサーバーでは、通常の使用時と同時起動時に、アクティブ、アイドル、待機中の接続数を、クエリレイテンシ、CPU、メモリ、ストレージレイテンシと併せて記録します。「too many clients」エラーは、1つのImmichコンテナが控えめに見える場合でも、全体の設定、別のサービス、または再起動の集中によって発生することがあります。
制限を変更する前に、すべてのPostgreSQLクライアントを把握する
各Immichサーバープロセスまたはレプリカ、マイグレーションやメンテナンスのタスク、バックアップジョブ、監視ツール、同じPostgreSQLインスタンスに接続する無関係なアプリケーションを一覧化します。可能であれば、それぞれに別のデータベースユーザーを割り当て、pg_stat_activityでどのクライアントがセッションを保持しているか確認できるようにします。現在のmax_connectionsを記録し、インシデント対応用の管理経路を1つ確保します。
Immichの「too many clients」に関するディスカッションには、そのリリースでImmichがデフォルトで10のプールを使用していたというプロジェクトコメントがあります。別の2026年のディスカッションでは、複数のImmichワーカーがそれぞれプールを維持できると説明されています。これらの数値はバージョン固有の実装上の参考情報として扱い、今後のリリースでそのまま掛け合わせる数値とは考えないでください。Immichがアイドル状態なのにデータベースがすでに接続上限近くにある場合は、Immichの調整を行う前に、そのセッションの所有者を特定します。アクティブなセッションが少ないのにクエリが遅い場合、接続数は主なボトルネックではなく、ストレージやクエリレイテンシの症状である可能性があります。
測定した同時実行数から接続予算を作成する
データベース管理、バックアップとリストアのツール、マイグレーション、監視用にセッションを確保します。
そのうえで、残りのアプリケーション接続を、同時に稼働するImmichプロセス数とその他のアプリケーションに割り当てます。目標は、通常の処理が不必要に待たされない程度に大きく、かつデータベースが効率的に実行できる範囲を超えないプールです。
PostgreSQLの接続プールサイズの分析では、理想的なプールは通常の需要に対応できる十分な大きさを持ちながら、実用上可能な限り小さくするものと説明されています。バックエンドセッションが少ないほど競合が減るためです。別のワークロードで使われているWebサーバーのプールサイズをそのまま流用するのではなく、観測したImmichの需要にこの原則を適用します。
Immichのリリースでサポートされたプールサイズの制御が公開されていない場合、目標の数値に合わせるためだけに内部実装を変更しないでください。制御できる項目、つまりアプリケーションのレプリカ数、無関係なクライアント、再起動のタイミング、バックアップの重複実行、データベースの容量を調整します。バージョンが変わったら、サポートされている設定を再評価します。
セッションを増やす前に、接続の頻繁な生成とデータベースの待機を減らす
Immich、分析、バックアップジョブ、その他のアプリケーションが一斉に再接続したり、同時にマイグレーションを実行したりしないよう、コンテナの起動を分散させます。PostgreSQLが利用可能になるまで待機するヘルスチェックやレディネスチェックを使用しますが、データベースがまだ復旧中の間に接続の集中を引き起こすような、間隔の短いリトライループは避けます。
ZimaSpaceの外部Immichデータベースの安全性に関するガイドは重要な境界を示しています。PostgreSQLをデフォルトのスタックから分離すると、バージョン、拡張機能、権限、バックアップ、ロールバックに関する責任が明確になります。遅いクエリやストレージの飽和を隠すことだけを目的に、接続プロキシや追加のデータベースホストを導入してはいけません。
アイドル状態のセッションが多く、アプリケーション数が正当に多い場合、PostgreSQLの一部のアーキテクチャでは、接続プールャーによってバックエンドセッション数を減らせることがあります。ただし、正確なImmichのバージョン、マイグレーション、トランザクションのセマンティクス、プリペアドステートメントの動作をテストしてから導入してください。プーリングは、制御不能になったクライアントや過負荷のデータベースを是正する代わりにはなりません。
同時アップロード、検索、ジョブ、再起動で検証する
再現可能なピーク状態を作ります。代表的なモバイルからのアップロード、過去の検索または閲覧操作、通常のバックグラウンドジョブを、想定される他のコンテナが稼働している状態で実行します。ユーザーや状態ごとの接続数、接続取得またはリクエストのエラー、クエリレイテンシ、データベースのCPU、メモリ、ディスクレイテンシを記録します。その後、1つだけ変更して再度実行します。
合格となる設定では、管理用の余裕を残したままセッション数が障害発生の上限を下回り、「too many clients」エラーが発生せず、クエリレイテンシが家庭内で設定した目標範囲に収まり、ピーク後にキューが処理されます。リクエストが実際にセッションの空きを待っており、同時にデータベースにCPU、メモリ、I/Oの余力がある場合に限って、接続数を増やす正当性があります。
アプリケーションスタックを再起動し、その後ホストも1回再起動して、接続数が最大になるバーストをテストします。起動時だけ障害が発生する場合は、恒久的な上限を引き上げるのではなく、起動順序やリトライ動作を修正します。時間の経過とともにセッションが蓄積する場合は、所有ユーザーとクエリを記録し、バージョン情報と接続状態の証拠を添えて、そのリークのパターンを調査に回します。
おすすめ商品
サポートとヒント
もっと読む
Immichでジョブやインポートの重複を防ぐ方法
重複するジョブと重複アセットを分離します。正規の取り込み経路を1つに統一し、再試行とパス変更を制御してから、小規模なコホートで再エントリーをテストします。
データベースのボリュームがいっぱいになった後に Immich を修復する方法
空き容量を確保するためにPostgreSQLのWALを削除しないでください。Immichへの書き込みを停止し、データベースの状態を保持したまま安全に容量を追加し、PostgreSQLを復旧してから、再発を防止してください。
Immichはなぜ所有者が間違った状態で欠落ファイルを再作成するのですか？
Immichは、失われたソース元ファイルを黙って再作成すべきではありません。再生成されたファイルの種類と作成者を特定し、作成時の識別情報を修正してください。
