Internal → external asset migration during the library unification — community workaround vs official path?

[PFalko]

Asking for direction, not asking for a merge. Read through the prior art before posting; cross-references at the bottom.

The use case

I migrated ~13,500 phone-uploaded assets from my Immich v2.7.5 internal upload directory into an external library this week (real production data, not a test setup). The community pattern by @bihius made it possible — direct SQL UPDATE setting originalPath, isExternal=true, libraryId=<uuid>, deviceId='Library Import', with the original sha1-content checksum and checksumAlgorithm='sha1' left untouched. Worked across 13,541 records in 15m51s, 0 failures, 12 content-drift cases correctly skipped.

That checksum detail is load-bearing — mobile bulk-upload-check (server/src/services/asset-media.service.ts bulkUploadCheck v2.7.5) matches by content sha1 only:

const checksums = dto.assets.map(a => fromChecksum(a.checksum));
const results = await this.assetRepository.getByChecksums(auth.user.id, checksums);

Rewrite checksumAlgorithm to 'sha1-path' (which library scan produces) and the phone re-uploads its entire library on the next sync. herbkk's #26397 is the same loop with zero replies; this hybrid record pattern is what avoids it.

Why I'm posting in Feature Request and not opening an Issue

Eight Discussions have already asked for this feature in various shapes (#5453, #10092, #12562, #22442, #26397, #27601, #28288, #4279). Maintainer responses to date:

@zackpollard, PR #12724 (2024-09-16) — closing rhyst's working PoC: "external libraries are currently under a feature freeze. This is due to us making vast changes to how they work with the rest of the codebase, trying to align them with how the default upload library works... right now we wouldn't be looking to merge something like this."

@bo0tzz, #12562 (2025-03-30): "The intent is to eventually unify everything so there is no longer the concept of an 'external' library."

@bo0tzz, #1699 (2025-09-21): "Another nice way to do this would be to have an option to 'absorb' an external library. That also gives you a preview of sorts before fully committing."

@bo0tzz, #27725 (2026-04-12): "Immich is not a file manager... external libraries are explicitly for you to manage the structure yourself."

So the direction seems clear: the unification refactor is in flight; external-library migration tooling is not getting added during the freeze. This Discussion isn't asking to land a PR that contradicts that. I want to ask a more specific question.

The refactor IS shipping right now

Just looking at main since the v2.7.5 tag (2026-04-13):

• PR chore!: remove deviceId and deviceAssetId #27818 (merged 2026-04-15, commit 8ee5d30) — chore!: remove deviceId and deviceAssetId — drops both columns from the asset schema entirely.
• Mobile-side: asset.entity.dart deleted (-575 lines), asset.entity.g.dart deleted (-3711), device_asset.entity.dart deleted, device_asset.model.dart deleted. New domain/models/asset/{remote,local}_asset.model.dart in their place. The mobile equivalent of the unification.
• Multiple feat! / chore! breaking changes accumulating: add isOwned filter to albums API, remove deprecated ML envs, require numpy 2.4. v2.8 is clearly close.

The question

When the deviceId-removal release ships, every existing community migration script (bihius's, herbkk's, mine) breaks the same day:

ERROR: column "deviceId" of relation "asset" does not exist

Two ways forward, and I'd like maintainer guidance on which:

1. Update community scripts to omit deviceId — keep isExternal=true + libraryId=<uuid> as the discriminator. From library.service.ts:407-416 on main (post the column drop), that pair is still what library scan stamps, so it should remain sufficient. Is that the right post-removal pattern?

2. Wait for the "absorb"-style endpoint @bo0tzz mentioned in #1699 — i.e., a server-side primitive that does this conversion correctly inside the service layer (proper event firing, audit, permissions). If that's on the roadmap, what's the rough timeline + can the community at least know whether to keep maintaining bihius-style SQL scripts in the meantime?

What I checked before posting

To save the duplicate-close reflex: I walked the v2.7.5 source for the hybrid record's safety across the 4 code paths that touch asset rows:

Path	File:line	Safe with hybrid record?
Library scan dedup	repositories/asset.repository.ts:1080-1100 (filterNewExternalAssetPaths)	Yes — filters by (originalPath, libraryId, isExternal), not by checksumAlgorithm
Mobile bulkUploadCheck	services/asset-media.service.ts bulkUploadCheck	Yes — content-sha1 match works on hybrid record
Storage Template	services/storage-template.service.ts:221-226	Skips by isExternal=true — never touches the file
handleAssetDeletion	services/asset.service.ts:362-365	unlink is gated on !isOffline, not on libraryId/isExternal — file gets removed correctly

Bug #24381 and #26601 are about offline external assets specifically — isOffline=true records. A migrated hybrid record has the file on disk (isOffline=false) and is unaffected by either.

I have not verified multi-user / partner-sharing / shared-album semantics — those would benefit from a maintainer eye even if just to say "treat as normal owner-only" or "this is what unification will change."

Closing

Real-world validation in case it adds signal: bihius/immich-migrate-to-external-library + a community PR I just opened (#3) ran across 13,541 records on a v2.7.5 production deployment. Full audit trail: source-walk, isolated test postgres validation, 100-pair smoke test, full run with per-pair content-sha1 drift detection. No data loss, no iPhone re-upload triggered.

Not asking for that PR to land here. Asking what to do next — both as a downstream user and as someone maintaining migration tooling that will break when the column drop ships.

Tagging Discussions referenced above so prior-art context is visible: #1699, #5453, #10092, #12562, #12724, #22442, #26397, #27725, #28288, #4279.

Disclosure: AI-assisted (Claude Code). Source-walk, prior-art collection, and the source quotes above were all verified against the actual Immich v2.7.5 + main branch before posting.

[github-actions[bot]]

This discussion has automatically been closed as it is likely a duplicate. We get a lot of duplicate threads each day, which is why we ask you in the template to confirm that you searched for duplicates before opening one. If you're sure this is not a duplicate, please leave a comment and we will reopen the thread if necessary.

[PFalko]

No duplicate.