cross-posted from: https://lemmy.world/post/50148512

Original post here [redlib link].

Written by deluan

The next release normalizes every ID in the database into a single format. It runs a one-time migration on first start. The PR with this change will be merged this weekend: https://github.com/navidrome/navidrome/pull/5824

If you run develop or auto-update, this lands soon (this weekend) and without warning. Make a backup of navidrome.db now. The migration is one-way, so rolling back (if needed) means restoring that backup.

The short version:

  • Takes ~30s to ~1m20s on my 96k-track library (QNAP Celeron). Scales with library size.
  • Everyone gets logged out once. Web UI and clients using the Navidrome API need to log in again. Subsonic clients authenticate per request, so they are unaffected.
  • Song IDs change, album and artist IDs do not. Clients that cache song IDs (offline downloads, cached playlists) may need a re-sync.
  • Cover art gets re-fetched, so the first browse after upgrading is slower.
  • Share links keep working.
  • Nothing is lost: favorites, ratings, play counts, bookmarks, play queues, scrobble history and Last.fm / ListenBrainz links all survive. No rescan needed.
  • One manual fix: .nsp smart playlists using inPlaylist or notInPlaylist keep the old playlist ID on disk and need updating by hand.

Full write-up: https://gist.github.com/deluan/917ebc243c8b486101de857ffae6739b

If you can, please test it with your favourite client once it is merged, and reply here (or on our Discord) if anything looks off.

EDIT: For app/client developers: I’ll merge the topSongsByArtistId PR at the same time as this ID migration. This means that you’ll be able to detect if a server is migrated by checking the getOpenSubsonicExtensions response and looking for the topSongsByArtistId extension.

  • Deebster@infosec.pubOPEnglish
    1·
    21 hours ago

    Below is deluan’s full write-up from https://gist.github.com/deluan/917ebc243c8b486101de857ffae6739b

    Hey folks,

    The next release normalizes every ID in the database into a single format. Navidrome accumulated three of them over the years (32-char hex hashes, UUIDs, and 22-char base62 strings), and this unifies them. Mostly housekeeping, but it makes ID handling predictable across the Subsonic, Jellyfin and native APIs, and unblocks some work on the Jellyfin side. (PR #5824)

    Especially relevant if you run develop or auto-update

    The PR gets merged soon, so develop users will hit this first, and anyone running Watchtower or a similar auto-updater will get it without warning. Make a backup of navidrome.db before that happens.

    The migration is one-way. There is no downgrade path, so going back to an older version means restoring that backup. It runs in a single transaction, so an interrupted upgrade rolls back and retries on the next start, but let it finish.

    How long it takes

    On my library (96k tracks, 727MB database) on a QNAP with a Celeron N5105: about 30 seconds warm, up to 1m20s on a cold start. It scales with library size, so a few thousand tracks will barely register.

    What changes

    1. Everyone gets logged out, once. The session signing key is rotated. Web UI and clients using Navidrome API need to log in again. Subsonic clients authenticate on every request, so they are unaffected.

    2. Song IDs change, album and artist IDs do not. About 98% of song IDs changed in my testing, and not a single album, artist or genre ID did. Clients that cache song IDs (offline downloads, cached playlists) may need a re-sync.

    3. Cover art gets re-fetched. Artwork cache keys include the IDs, so the cache starts cold and artist images are pulled from the external providers again. The first browse after upgrading is slower than usual.

    4. Share links keep working. URLs are unchanged and their contents get remapped.

    The .nsp gotcha

    If you use file-based smart playlists with inPlaylist or notInPlaylist, those rules reference another playlist by ID. The migration updates the database, but the .nsp file on disk still has the old ID, and the file wins on the next import. Grab the new ID from the playlist URL in the UI and update the file.

    What does not change

    Favorites, ratings, play counts, last played dates, bookmarks, play queues, scrobble history, and your Last.fm / ListenBrainz links are all preserved. I checked this against a copy of my production database: every annotation, bookmark, scrobble and play queue matched exactly before and after. No rescan needed.

    (Legacy PID.Album or PID.Track configs will trigger a full rescan on the next start. That one is intentional.)

    If you can, please test it with your favourite client and let me know if you have questions (in #general-and-support )