Can Immich Use an External Database Without Breaking Upgrades?

Immich can be pointed at an external PostgreSQL service, but that does not make upgrades automatically safe; it moves database version, extension, privilege, backup, and rollback responsibility outside the default stack.

Treat an external database as an advanced compatibility boundary, not a performance checkbox. Before each Immich or PostgreSQL upgrade, verify the requirements of the exact Immich release you plan to run, confirm that the external server can provide the required extensions and privileges, make a restorable backup, and change one upgrade layer at a time so you know which component introduced a failure.

Start With the External Database Contract

Document the database endpoint, database name, service account, TLS mode, PostgreSQL major version, installed extension names and versions, and who can upgrade those extensions. Keep this record beside the Immich deployment definition so a container recreation does not silently reconnect to a different server or database.

A pre-existing PostgreSQL server is possible but is not Immich’s default recommended setup. For current releases, the standalone-database path requires pgvector plus VectorChord; Immich is known to work with PostgreSQL 14 through 19, pgvector >=0.7 and <0.9, and VectorChord >=0.3 and <2.0. Recheck these ranges before every upgrade because they can change.

Plan privileges before cutover. Immich typically expects a database role with superuser permission; running without it is an advanced path that can require manual intervention during updates, and current automated database backups require superuser permission. If your external provider cannot satisfy those requirements, stop before moving production state.

Verify PostgreSQL and Extension Compatibility Before Changing Anything

List the current and target PostgreSQL versions together with every extension Immich depends on. A major PostgreSQL upgrade can require extension binaries that are built for the target major version, while an Immich upgrade may require a newer extension or migration behavior even if PostgreSQL itself still starts.

Extension package files and the SQL extension state have to move deliberately with the database rather than being assumed to follow a PostgreSQL upgrade. Review PostgreSQL extension upgrade dependencies before changing the database major version or the extension packages that Immich requires.

If your external provider does not let you install or upgrade the required extension, change shared preload settings when required, or grant the privileges the migration needs, stop before updating Immich. A database that accepts ordinary queries can still be unsuitable for the next application migration.

Keep Database Major Upgrades Separate From Immich Upgrades

Avoid combining a PostgreSQL major upgrade, extension upgrade, and Immich application upgrade in one maintenance event unless you have already rehearsed the full sequence. When several compatibility boundaries move together, a failed startup no longer tells you which layer caused it.

Minor PostgreSQL updates and major-version upgrades are different maintenance events, and major upgrades require the target environment—including third-party extensions—to be prepared first. Keep PostgreSQL major-version upgrades separate from an Immich application upgrade whenever possible so a failed startup still has one clear change to investigate.

For a home server, the lowest-risk sequence is usually: capture backups, verify a restore, update one layer, run validation, then continue. If an Immich release requires a database change, follow that release’s prescribed order instead of applying a generic PostgreSQL upgrade recipe.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Preserve a Rollback Path That Covers Both Database and Media

An external database makes it easier to forget that Immich state is split across PostgreSQL and the media library. Back up the database with a database-consistent method and preserve the relevant media/configuration state from the same recovery window before a migration that can change schemas or asset metadata.

Database state, application files, configuration, and uploads have to agree at restore time. Use a consistent database-container backup as the acceptance model, not simply whether PostgreSQL starts.

Do not call rollback ready until you know what happens to both sides if the application migration succeeds partially. Keep the old application version, deployment definition, database backup, and media state available long enough to recover without writing newer state over the only known-good copy.

Validate the Upgrade as an Application, Not Just a Database Connection

After the change, confirm PostgreSQL accepts the intended Immich role, required extensions are present at expected versions, and the Immich migration completes without repeated database errors. A successful TCP connection or `SELECT 1` proves connectivity, not application compatibility.

Then use Immich normally: load old albums, open representative photos and videos, search, inspect users or sharing where relevant, and upload one disposable asset. Watch application and database logs during these actions for missing extensions, permission errors, migration failures, or repeated retries.

Only after the application passes those checks should you resume normal backup retention and remove the rollback copy. If the external database repeatedly makes routine Immich upgrades depend on manual extension or privilege work that you cannot reliably rehearse, the default dedicated database lifecycle is the safer operational choice.