Immichはアップグレードを壊さずに外部データベースを使用できますか？

エヴァ・ウォン

IceWhale author

エヴァ・ウォン は テクニカルライター であり ZimaSpaceの常駐ティンカーでもあります。 生涯のオタクであり、 ホームラボとオープンソースソフトウェアに情熱を持っています。彼女は複雑な技術的概念をわかりやすく、 実践的なガイドに翻訳することを専門としています。エヴァはセルフホスティングは楽しくあるべきで、怖がるものではないと信じています。彼女のチュートリアルを通じて、コミュニティが ハードウェアのセットアップを解明する手助けをしています。初めてのNAS構築からDockerコンテナの習得まで。

Can Immich Use an External Database Without Breaking Upgrades? - Zima Store Online

Immichは外部のPostgreSQLサービスを指定できますが、それによってアップグレードが自動的に安全になるわけではありません。データベースのバージョン、拡張機能、権限、バックアップ、ロールバックに関する責任が、デフォルトのスタックの外部へ移るだけです。

外部データベースは、性能上の設定ではなく、高度な互換性の境界として扱ってください。ImmichまたはPostgreSQLをアップグレードする前に、実行予定のImmichの正確なリリース要件を確認し、外部サーバーが必要な拡張機能と権限を提供できることを確認し、復元可能なバックアップを作成してください。また、どのコンポーネントが障害を引き起こしたのか分かるように、一度に1つのアップグレード層だけを変更します。

外部データベースの契約から始める

データベースのエンドポイント、データベース名、サービスアカウント、TLSモード、PostgreSQLのメジャーバージョン、インストール済みの拡張機能の名前とバージョン、そしてそれらの拡張機能をアップグレードできる担当者を文書化します。コンテナを再作成した際に、別のサーバーやデータベースへ気付かないまま再接続しないよう、この記録をImmichのデプロイ定義と一緒に保管してください。

既存のPostgreSQLサーバーを使用することは可能ですが、Immichがデフォルトで推奨している構成ではありません。現行リリースでは、スタンドアロンデータベース構成にpgvectorとVectorChordが必要です。ImmichはPostgreSQL 14～19、pgvector >=0.7かつ<0.9、VectorChord >=0.3かつ<2.0で動作することが確認されています。これらの範囲は変更される可能性があるため、アップグレードのたびに再確認してください。

切り替え前に権限を計画します。Immichは通常、スーパーユーザー権限を持つデータベースロールを想定しています。スーパーユーザー権限なしで実行する場合は、更新時に手動対応が必要になることがある高度な構成であり、現在の自動データベースバックアップにもスーパーユーザー権限が必要です。外部プロバイダーがこれらの要件を満たせない場合は、本番環境の状態を移行する前に中止してください。

変更前にPostgreSQLと拡張機能の互換性を確認する

現在および移行先のPostgreSQLのバージョンと、Immichが依存するすべての拡張機能を一覧にします。PostgreSQLのメジャーアップグレードでは、移行先のメジャーバージョン向けにビルドされた拡張機能のバイナリが必要になる場合があります。一方、Immichのアップグレードでは、PostgreSQL自体が起動し続けていても、より新しい拡張機能や異なるマイグレーション動作が必要になることがあります。

拡張機能のパッケージファイルとSQL拡張機能の状態は、PostgreSQLのアップグレードに伴って自動的に移行すると考えず、データベースとともに意図的に移行する必要があります。Immichが必要とするデータベースのメジャーバージョンや拡張機能パッケージを変更する前に、PostgreSQL拡張機能のアップグレードに関する依存関係を確認してください。

外部プロバイダーによって必要な拡張機能のインストールやアップグレード、必要に応じた共有プリロード設定の変更、マイグレーションに必要な権限の付与が許可されていない場合は、Immichの更新前に中止してください。通常のクエリを受け付けるデータベースでも、次のアプリケーションマイグレーションには適さない可能性があります。

データベースのメジャーアップグレードとImmichのアップグレードを分ける

十分に一連の手順をリハーサル済みでない限り、PostgreSQLのメジャーアップグレード、拡張機能のアップグレード、Immichアプリケーションのアップグレードを1回のメンテナンスで同時に行うことは避けてください。複数の互換性の境界を同時に変更すると、起動に失敗しても、どの層が原因なのか分からなくなります。

PostgreSQLのマイナーアップデートとメジャーバージョンアップグレードは異なるメンテナンス作業であり、メジャーアップグレードでは、サードパーティ製の拡張機能を含む移行先環境を事前に準備する必要があります。起動に失敗した場合でも調査すべき変更を1つに絞れるよう、可能な限りPostgreSQLのメジャーバージョンアップグレードとImmichアプリケーションのアップグレードを分けてください。

ホームサーバーでは、通常、バックアップを取得し、復元を確認し、1つの層を更新し、検証を実行してから次へ進む手順が最もリスクの低い方法です。Immichのリリースでデータベースの変更が必要な場合は、一般的なPostgreSQLのアップグレード手順ではなく、そのリリースで指定された順序に従ってください。

Featured

ZimaCube 2 パーソナルクラウドホームNAS

ZimaCube2

データベースとメディアの両方を対象とするロールバック経路を確保する

外部データベースを使用すると、Immichの状態がPostgreSQLとメディアライブラリに分かれていることを忘れやすくなります。スキーマやアセットのメタデータを変更する可能性のあるマイグレーションの前に、データベース整合性を保てる方法でデータベースをバックアップし、同じ復旧時点の関連するメディアおよび設定の状態を保存してください。

復元時には、データベースの状態、アプリケーションファイル、設定、アップロードデータが一致していなければなりません。単にPostgreSQLが起動するかどうかではなく、整合性のあるデータベースコンテナのバックアップを受け入れ基準として使用してください。

アプリケーションのマイグレーションが部分的に成功した場合に、両方の側で何が起きるのかを把握するまで、ロールバックの準備ができたとは考えないでください。新しい状態で唯一の正常なコピーを上書きせずに復旧できるよう、旧バージョンのアプリケーション、デプロイ定義、データベースバックアップ、メディアの状態を十分な期間保持してください。

データベース接続だけでなく、アプリケーションとしてアップグレードを検証する

変更後は、PostgreSQLが想定したImmichロールを受け入れること、必要な拡張機能が期待されるバージョンで存在すること、Immichのマイグレーションが繰り返し発生するデータベースエラーなしに完了することを確認します。TCP接続や`SELECT 1`が成功しても、それは接続性を証明するだけで、アプリケーションの互換性を証明するものではありません。

次に、通常どおりImmichを使用します。以前のアルバムを読み込み、代表的な写真や動画を開き、検索を実行し、必要に応じてユーザーや共有を確認し、使い捨てのアセットを1つアップロードしてください。これらの操作中に、拡張機能の不足、権限エラー、マイグレーションの失敗、繰り返される再試行がないか、アプリケーションとデータベースのログを監視します。

アプリケーションがこれらのチェックに合格してから、通常のバックアップ保持を再開し、ロールバック用コピーを削除してください。外部データベースによって、通常のImmichアップグレードが、確実にリハーサルできない手動の拡張機能操作や権限作業に繰り返し依存する場合は、デフォルトの専用データベースのライフサイクルを選ぶほうが、安全な運用上の選択肢です。