Immich v3 quietly swapped my vector database — read the release notes to the end
Immich is the self-hosted Google Photos replacement everyone recommends, and deservedly — it ships features faster than almost anything in the homelab world. It also just reminded me, with its version 3 release, that "ships features fast" and "boring, set-and-forget backup for your irreplaceable family photos" are in tension. If you run Immich, the v3 upgrade will happily swap the database engine underneath your library, and it will not make a big deal of telling you.
What changed
Immich 3.0.0 landed on 2 July 2026; 3.1.0 followed on 29 July, and the 3.2 line is cooking right now (3.2.0-rc.3 was tagged on 4 September). So it's both a fresh major and actively moving. The upgrade itself starts simple — Docker users flip IMMICH_VERSION from v2 to v3 before pulling. The catch is underneath.
Immich uses a Postgres extension for the vector search that powers face recognition and "find similar" — and v3 removed support for the old pgvecto.rs extension (which went unmaintained) in favour of its successor, VectorChord. If your compose file still points at the old vector image, the v3 container won't come up clean until you migrate the extension first. That's not a config tweak; it's a change to the storage engine your library depends on, on a point-major bump.
There's more re-architecture in the release, most of it aimed at developers: backend validation moved to Zod with structured error responses, the old timeline-sync system was removed, and a batch of deprecated API endpoints, env vars, and response fields were dropped. Immich's own notes wave a lot of this off as "breaking changes that only affect third-party tools that integrate with the API" — which is true of the API bits, and quietly not the whole story, because the vector-extension swap affects the person running the container, full stop.
"These breaking changes only affect third-party API integrations" is the most reassuring sentence in the release notes, and the vector-database migration sitting three paragraphs down is proof it isn't the whole truth.
The honest tension
I want to be fair: Immich is genuinely excellent, and the v3 feature list is real — non-destructive mobile editing, a preview Workflows system, real-time HLS video transcoding, filesystem integrity checks, on-device OCR. This is a project that out-ships its commercial competition. But there's a property you want from the thing holding your only copy of a decade of photos, and it's not velocity. It's the opposite: you want it to be boring, to change slowly, to never reorganise itself under you. Immich is the fast-moving option in a category where I'd argue slow-moving is the feature.
That's not a reason to drop it — it's a reason to run it like the precious thing it guards. Concretely, and this is the same discipline I keep preaching about backups: before you ever docker compose pull a new Immich major, read the release notes to the end (the landmine is rarely at the top), and snapshot the database first. Not "back up eventually" — snapshot the Postgres volume the moment before you pull, so a failed extension migration is a five-minute rollback instead of a bad evening. Pin your IMMICH_VERSION to a specific tag, never latest, so an upgrade is always a decision you made and not one a docker compose pull made for you.
And the quiet contrarian thought underneath all of it: for pure archival — the "I never want to lose these" layer, as opposed to the "browse and share" layer — boring flat files and a dumb one-way sync still beat a database-backed app that reorganises itself twice a quarter. Run Immich for the lovely browsing experience. Keep a separate, boring, app-independent copy of the actual files for the day Immich's next clever migration doesn't go your way.