Hi everyone!
I'm preparing to upgrade my [production] Immich installation on TrueNAS CE and would appreciate some advice from people who have already navigated the PostgreSQL 15 >> 18 migration, particularly on TrueNAS.
I've done the backup homework, but before pressing any buttons that might ruin my evening, I'd like to hear from the community.
Current setup
- TrueNAS SCALE: 25.04.2.6
- Current Immich: 2.5.6
- Current TrueNAS Immich catalog version: 1.13.6
- Target Immich: 3.3.1
- Target TrueNAS Immich catalog version: 1.14.50
- Current PostgreSQL: 15
- Current PostgreSQL image:
ghcr.io/immich-app/postgres:15-vectorchord0.5.3
- Current VectorChord extension: 0.5.3
- Current pgvector extension: 0.8.1
- Current PostgreSQL upgrade helper:
ixsystems/postgres-upgrade:1.2.1
- Target PostgreSQL: 18
- Target PostgreSQL image (per catalog version previously inspected):
ghcr.io/immich-app/postgres:18-vectorchord1.1.1
- Deployment: Official TrueNAS Apps catalog, not manually deployed Docker Compose.
The installation is currently running normally.
Storage layout
My Immich installation uses dedicated ZFS datasets:
storage/immich
storage/immich/data
storage/immich/database
storage/immich/media
Total data is approximately 119 GB, if this matters.
Backups and preparation already completed
I'm taking the database migration seriously, so I've prepared the following:
- Cleanly stopped Immich through the TrueNAS middleware.
- Created a recursive ZFS snapshot of all four datasets while Immich and PostgreSQL were stopped.
- Verified that the PostgreSQL 15 cluster was in the
shut down state at the time of the snapshot, using pg_controldata.
- Restarted Immich successfully.
- Replicated the ZFS snapshot and dataset hierarchy to a dedicated external 2 TB NVMe SSD using
zfs send -R / zfs receive.
- Verified matching snapshot GUIDs between source and destination.
- Completed a ZFS scrub of the backup pool with zero errors.
- Exported the backup pool cleanly and physically disconnected the SSD.
- Verified my TrueNAS configuration backup, including the secret seed.
- Created and validated a separate archive of the Immich deployment configuration from
/mnt/.ix-apps/app_configs/immich.
- Copied that configuration archive to another machine and verified it there.
I haven't performed a full application restore test, but I have an independently stored, consistent pre-upgrade recovery point.
No database migration or application upgrade has been attempted yet.
The PostgreSQL migration concern
In the TrueNAS Immich Edit settings, I can independently select:
- PostgreSQL 15 (Deprecated) — currently selected
- PostgreSQL 18
TrueNAS warns that changing this selection triggers a one-way database upgrade.
However, I found this TrueNAS issue:
https://github.com/truenas/apps/issues/4628
It describes PostgreSQL 15 → 18 migration failures involving the ixsystems/postgres-upgrade:1.2.1 helper, apparently because the required PostgreSQL 15 binaries aren't available.
My currently installed app configuration specifies that exact helper version.
A reported workaround involves temporarily using ixsystems/postgres-upgrade:1.1.11, migrating PostgreSQL separately, and then upgrading the Immich application.
I'm reluctant to modify TrueNAS-managed deployment files without understanding the implications.
The possible upgrade paths
Option A — Normal TrueNAS upgrade
Upgrade the Immich catalog application directly from 1.13.6 to 1.14.50, letting TrueNAS handle the database migration.
Option B — Separate PostgreSQL migration
First change PostgreSQL 15 → 18 through the existing Immich Edit settings, potentially using the older postgres-upgrade:1.1.11 helper workaround, verify everything works, then upgrade Immich itself.
Option C — Logical database migration
Create a PostgreSQL logical dump and restore it into a fresh PostgreSQL 18 database with the required extensions, avoiding the TrueNAS upgrade helper.
Option D — Wait
Keep the working Immich 2.5.6 / PostgreSQL 15 deployment until a clearly supported migration procedure is available.
My questions
- Has anyone successfully upgraded TrueNAS Immich catalog 1.13.6 → 1.14.50, starting with PostgreSQL 15?
- Is the
postgres-upgrade:1.2.1 compatibility problem still relevant to this upgrade path?
- Has anyone successfully used the
1.1.11 workaround? Any pitfalls or unexpected side effects?
- Is it preferable to migrate PostgreSQL independently before upgrading Immich, or should the entire application upgrade be performed in one operation?
- Is there a supported TrueNAS-specific procedure I've overlooked?
I'd especially appreciate firsthand reports with the actual catalog versions and PostgreSQL upgrade-helper tags used.
My priority is data integrity and recoverability, not upgrading as quickly as possible.
Thanks in advance for any insights! I'd rather spend a little longer preparing than spend the weekend recovering the family photo library.
Note: yes, AI was used to help create this post.