Issues with upgrading postgres

[wboui]

Hello,

When I first set up Immich some months ago I used a docker compose that pulled this postgres image: tensorchord/pgvecto-rs:pg16-v0.2.1. I am now trying to revert to the official compose, but none of the images seem to work. I think it's because I need to do a clean migration but I honestly have no idea how to do that.

1. is there a way for this migration to happen automatically?
2. if not, is there a recommended "migrate postgress databases for dummies" guide somewhere? If relevant, I'm on a Synology NAS.
3. if not, which is the latest image of postgres on ghcr.io/immich-app/postgres that I can use with my current database?

The initial image does work with Immich 2.7.5 but I'm concerned that staying on that old version will break something down the line someday.

Thank you!

[Mraedis]

You should first use 16-vectorchord0.5.3-pgvector0.8.1
This image has both the pgvector and vectorchord built in, allowing yuo to migrate.

If it doesn't work, please post your logs.

[wboui]

Thanks! I can spin up postgres with this but Immich crashes; the log indicates: PostgresError: could not access file "$libdir/vectors": No such file or directory

Is there a manual step I need to take to perform the migration?

[Mraedis]

There should not be, I might have missed with the image because there's pgvecto.rs and pgvectors, could you try 16-vectorchord0.4.2-pgvector0.8.1-pgvectors0.2.1

[wboui]

I'm getting another error: "Error: The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. If VectorChord 0.5.3 is compatible with Immich, please ensure the Postgres instance has this available."

edit: This is probably due to my trying to upgrade yesterday with later versions that immich_server didn't like for various reasons. For now I can still spin up the stack with the initial tensorchord/pgvecto-rs:pg16-v0.2.1.

[Mraedis]

This is embarassing but there is no vchord0.5.3 image with pgvecto.rs0.2.1 so you'll have to restore from backup to a pre-upgraded database and then go to vectorchord0.4.2-pgvector0.8.1-pgvectors0.2.1 once again, then you can go to 16-vectorchord0.5.3

[wboui]

Thanks! Didn't even know Immich backed up the database daily, and thank god for that! I was able to roll back to a pre-upgrade version (yesterday - didn't lose anything) and then re-upgraded to 16-vectorchord0.5.3-pgvector0.8.1. So now at least I'm back on the right repo! However, upgrades to 17 and 18 both fail. Is it recommended to do them or not yet? I think the official compose that came with v2.7.5 still has 14 so I suppose 16 isn't too bad but I might as well take this to the end?

The log when I try 17 is:

2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.717 UTC [1] DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.8 (Debian 17.8-1.pgdg12+1).
2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.717 UTC [1] FATAL:  database files are incompatible with server
2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.716 GMT [1] LOG:  skipping missing configuration file "/var/lib/postgresql/data/postgresql.override.conf"
2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.716 GMT [1] LOG:  skipping missing configuration file "/etc/postgresql/postgresql.override.conf"
2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.716 GMT [1] LOG:  skipping missing configuration file "/var/lib/postgresql/data/postgresql.override.conf"
2026/04/15 21:29:02 | stderr | 2026-04-15 19:29:02.715 GMT [1] LOG:  skipping missing configuration file "/etc/postgresql/postgresql.override.conf"
2026/04/15 21:29:02 | stdout |  
2026/04/15 21:29:02 | stdout | PostgreSQL Database directory appears to contain a database; Skipping initialization

And if I try 18:

2026/04/15 21:35:36 | stderr | discussion around this process, and suggestions for how to do so.
2026/04/15 21:35:36 | stderr | See https://github.com/docker-library/postgres/issues/37 for a (long)
2026/04/15 21:35:36 | stderr |  
2026/04/15 21:35:36 | stderr | boundary issues.
2026/04/15 21:35:36 | stderr | subdirectory, allowing usage of "pg_upgrade --link" without mount point
2026/04/15 21:35:36 | stderr | at /var/lib/postgresql which will then place PostgreSQL data in a
2026/04/15 21:35:36 | stderr | The suggested container configuration for 18+ is to place a single mount
2026/04/15 21:35:36 | stderr |  
2026/04/15 21:35:36 | stderr | versions).
2026/04/15 21:35:36 | stderr | upgrading the underlying database using "pg_upgrade" (which requires both
2026/04/15 21:35:36 | stderr | This is usually the result of upgrading the Docker image without
2026/04/15 21:35:36 | stderr |  
2026/04/15 21:35:36 | stderr | /var/lib/postgresql/data
2026/04/15 21:35:36 | stderr | Counter to that, there appears to be PostgreSQL data in:
2026/04/15 21:35:36 | stderr |  
2026/04/15 21:35:36 | stderr | See also https://github.com/docker-library/postgres/pull/1259
2026/04/15 21:35:36 | stderr |  
2026/04/15 21:35:36 | stderr | PostgreSQL itself works, and how upgrades are to be performed.
2026/04/15 21:35:36 | stderr | major-version-specific directory names).  This better reflects how
2026/04/15 21:35:36 | stderr | format which is compatible with "pg_ctlcluster" (specifically, using
2026/04/15 21:35:36 | stderr | Error: in 18+, these Docker images are configured to store database data in a

[wboui]

I actually found a solution in this thread: #24831. Am now on version 18 with my database intact! Thanks a lot for the help!

[AndrewHoover]

This is embarassing but there is no vchord0.5.3 image with pgvecto.rs0.2.1 so you'll have to restore from backup to a pre-upgraded database and then go to vectorchord0.4.2-pgvector0.8.1-pgvectors0.2.1 once again, then you can go to 16-vectorchord0.5.3

How do you do this? I have tried pulling to a new image but I get a login screen that I can't login to rather than the create new admin account as expected so that I can recover from backup.

[EHRETic]

Thanks a lot @Mraedis , this helped me a lot migrating mine! 👌😉

[swagtherius]

For anyone still wedged here because no image ships both vchord 0.5.3 and pgvecto.rs at once — I built a disposable bridge image that gets you across, and wrote up the full runbook. (This is the gap @Mraedis noted above; the pgvecto.rs-bearing images cap at vchord 0.4.2, so once your DB is at vchord 0.5.3 you can't boot anything that still needs vectors.so.)

The wedge

• DB has vchord 0.5.3 → older-vchord images fail with invalidDowngrade (0.5.3 activated, only 0.3.0 available).
• DB data still has pgvecto.rs (vectors.so) columns/indexes → images without pgvecto.rs fail with could not access file "$libdir/vectors".

You need one image with both, just long enough to reindex off pgvecto.rs onto VectorChord, then drop pgvecto.rs and move to a clean image.

The image

docker pull nicotbsolutions/immich-postgres:16-vchord0.5.3-with-pgvectors
Docker Hub: https://hub.docker.com/r/nicotbsolutions/immich-postgres

It's the official 16-vectorchord0.5.3-pgvector0.8.1 image with pgvecto.rs's vectors.so + extension files copied in from 16-vectorchord0.4.2-pgvector0.8.1-pgvectors0.2.1. Disposable bridge only — third-party and amd64-only, so inspect it or rebuild from the Dockerfile below (arm64 users must rebuild).

Dockerfile

# Stage that still contains pgvecto.rs (vectors.so + its extension files)
FROM ghcr.io/immich-app/postgres:16-vectorchord0.4.2-pgvector0.8.1-pgvectors0.2.1 AS bridge

# Final image: has vchord 0.5.3 (satisfies the DB) + pgvector, but NO pgvecto.rs
FROM ghcr.io/immich-app/postgres:16-vectorchord0.5.3-pgvector0.8.1

# Bring pgvecto.rs across: the loadable library + its extension control/SQL files.
COPY --from=bridge /usr/lib/postgresql/16/lib/vectors.so        /usr/lib/postgresql/16/lib/vectors.so
COPY --from=bridge /usr/share/postgresql/16/extension/vectors*  /usr/share/postgresql/16/extension/

# Fail the build immediately if any expected file is missing / paths changed.
RUN set -eux; \
    test -f /usr/lib/postgresql/16/lib/vectors.so; \
    test -f /usr/lib/postgresql/16/lib/vchord.so; \
    ls -la /usr/share/postgresql/16/extension/vectors*; \
    ls -la /usr/lib/postgresql/16/lib/vectors.so /usr/lib/postgresql/16/lib/vchord.so

Runbook

0. Back up your Postgres appdata folder first (fully reversible; photos are never touched, only ML indexes get rebuilt).
1. Point the Postgres container at this image and boot it.
2. Preload vectors.so alongside vchord.so. The template hardcodes shared_preload_libraries = 'vchord.so', so override it in a config file — put this exact line (single quotes, no double quotes) into <pgdata>/postgresql.auto.conf:

   shared_preload_libraries = 'vchord.so, vectors.so'
   

   Two traps worth flagging: don't use ALTER SYSTEM SET for this (it wraps the comma value in one quote set → Postgres tries to load a single file named vchord.so, vectors.so and won't start), and it must be single quotes. Verify with SHOW shared_preload_libraries; → vchord.so, vectors.so.
3. Start Immich; let it reindex clip_index/face_index off pgvecto.rs onto VectorChord.
4. Drop pgvecto.rs:

   DROP EXTENSION IF EXISTS vectors CASCADE;
   DROP SCHEMA    IF EXISTS vectors CASCADE;

5. Cut over to a clean official 16-vectorchord0.5.3 (or 16-vectorchord1.1.1) image and set shared_preload_libraries back to just 'vchord.so'. Delete the bridge image.