feat(plex): add source/remote_id columns for Plex source tracking (TASK-342.2)

Add idempotent migrations for source TEXT NOT NULL DEFAULT 'local' and
remote_id TEXT to the library table, with idx_library_source and
idx_library_remote_id indexes. Update Track model, row_to_track, all
SELECT statements, and library_get_all with optional source_filter param.

Author: pythoninthegrass

backlog/tasks/task-342.2 - Backend-Database-migration-for-Plex-source-tracking.md

@@ -1,10 +1,10 @@
 ---
 id: TASK-342.2
 title: 'Backend: Database migration for Plex source tracking'
-status: In Progress
+status: Done
 assignee: []
 created_date: '2026-05-21 22:56'
-updated_date: '2026-05-22 04:31'
+updated_date: '2026-05-23 00:48'
 labels: []
 dependencies: []
 parent_task_id: TASK-342
@@ -32,13 +32,69 @@ Key files:
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 Schema migration follows the column-presence idiom in `crates/mt-tauri/src/db/schema.rs::run_migrations` — read columns via `get_table_columns(conn, "library")`, then `conn.execute("ALTER TABLE library ADD COLUMN X ...", [])` guarded by `if !cols.contains(...)`. Do not introduce `PRAGMA user_version` or any new versioning system.
-- [ ] #2 New columns on `library`: `source TEXT NOT NULL DEFAULT 'local'` and `remote_id TEXT`. Existing rows acquire `source='local'` via the DEFAULT; `remote_id` stays NULL.
-- [ ] #3 Add index `idx_library_remote_id ON library(remote_id) WHERE remote_id IS NOT NULL`, created behind an `index_exists(conn, "idx_library_remote_id")?` guard.
-- [ ] #4 Add index `idx_library_source ON library(source)`, created behind an `index_exists` guard, to support `WHERE source = ?` filters efficiently.
-- [ ] #5 The `Track` model in `crates/mt-tauri/src/db/models.rs` gains `source: String` (default `"local"` in constructors) and `remote_id: Option<String>`. All existing row-builder functions read the new columns.
-- [ ] #6 Existing library queries (`library_get_all`, `library_get_section` in `crates/mt-tauri/src/library/commands.rs`) continue to return all tracks by default (no source filter on the WHERE clause). A new optional `source_filter: Option<String>` parameter is added to `library_get_all`; when `Some("local")` or `Some("plex")` it appends `AND source = ?`. When `None`, behavior is unchanged.
-- [ ] #7 Library stats (`library_get_stats` at `commands.rs:476`) count both sources — no change required (existing query has no source filter).
-- [ ] #8 Migration is verified idempotent by a Rust unit test that runs `run_migrations` twice in a row against a fresh in-memory SQLite DB and asserts (a) both new columns exist after the first call, (b) the second call is a no-op (no error, no duplicate columns).
-- [ ] #9 A second test inserts one row with `source='local'`, one with `source='plex'` + `remote_id='12345'`, and asserts `library_get_all(source_filter=Some("plex"))` returns exactly the second row.
+- [x] #1 Schema migration follows the column-presence idiom in `crates/mt-tauri/src/db/schema.rs::run_migrations` — read columns via `get_table_columns(conn, "library")`, then `conn.execute("ALTER TABLE library ADD COLUMN X ...", [])` guarded by `if !cols.contains(...)`. Do not introduce `PRAGMA user_version` or any new versioning system.
+- [x] #2 New columns on `library`: `source TEXT NOT NULL DEFAULT 'local'` and `remote_id TEXT`. Existing rows acquire `source='local'` via the DEFAULT; `remote_id` stays NULL.
+- [x] #3 Add index `idx_library_remote_id ON library(remote_id) WHERE remote_id IS NOT NULL`, created behind an `index_exists(conn, "idx_library_remote_id")?` guard.
+- [x] #4 Add index `idx_library_source ON library(source)`, created behind an `index_exists` guard, to support `WHERE source = ?` filters efficiently.
+- [x] #5 The `Track` model in `crates/mt-tauri/src/db/models.rs` gains `source: String` (default `"local"` in constructors) and `remote_id: Option<String>`. All existing row-builder functions read the new columns.
+- [x] #6 Existing library queries (`library_get_all`, `library_get_section` in `crates/mt-tauri/src/library/commands.rs`) continue to return all tracks by default (no source filter on the WHERE clause). A new optional `source_filter: Option<String>` parameter is added to `library_get_all`; when `Some("local")` or `Some("plex")` it appends `AND source = ?`. When `None`, behavior is unchanged.
+- [x] #7 Library stats (`library_get_stats` at `commands.rs:476`) count both sources — no change required (existing query has no source filter).
+- [x] #8 Migration is verified idempotent by a Rust unit test that runs `run_migrations` twice in a row against a fresh in-memory SQLite DB and asserts (a) both new columns exist after the first call, (b) the second call is a no-op (no error, no duplicate columns).
+- [x] #9 A second test inserts one row with `source='local'`, one with `source='plex'` + `remote_id='12345'`, and asserts `library_get_all(source_filter=Some("plex"))` returns exactly the second row.
 <!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+## Implementation Plan
+
+### Files to modify
+1. `crates/mt-tauri/src/db/schema.rs` — 4 new migrations + update existing idempotent test
+2. `crates/mt-tauri/src/db/models.rs` — add `source: String` and `remote_id: Option<String>` to Track
+3. `crates/mt-tauri/src/db/library.rs` — row_to_track, LibraryQuery, build_library_where, 7 SELECT statements, add source_filter test
+4. `crates/mt-tauri/src/library/commands.rs` — add source_filter param to library_get_all, fix get_section_all struct literal
+5. `crates/mt-tauri/src/db/playlists.rs` — add l.source, l.remote_id to JOIN SELECT
+
+### Migrations (schema.rs)
+Append to end of run_migrations before Ok(()):
+- source TEXT NOT NULL DEFAULT 'local' (guarded by column check)
+- remote_id TEXT (guarded by column check)
+- idx_library_remote_id partial index WHERE remote_id IS NOT NULL
+- idx_library_source index
+
+### Model changes (models.rs)
+Add to Track struct after last_seen_at:
+- `pub source: String`
+- `pub remote_id: Option<String>`
+
+### Library query changes (library.rs)
+- row_to_track: add source + remote_id reads with unwrap_or fallbacks
+- LibraryQuery: add `source_filter: Option<String>` field
+- build_library_where: add condition when source_filter is Some
+- 7 SELECT statements: add `source, remote_id` to column list
+  - get_all_tracks (~line 135)
+  - find_tracks_by_artist_title (~line 330)
+  - get_track_by_id (~line 364)
+  - get_track_by_filepath (~line 382)
+  - get_missing_tracks (~line 960)
+  - find_missing_track_by_inode (~line 1000)
+  - find_missing_track_by_content_hash (~line 1022)
+- Add test_source_filter test (AC#9)
+
+### Command changes (commands.rs)
+- library_get_all: add source_filter: Option<String> param, pass to LibraryQuery
+- get_section_all (line 221): add source_filter: None to struct literal
+
+### Playlist changes (playlists.rs)
+- JOIN SELECT (~line 93): add l.source, l.remote_id columns
+
+### Tests
+- schema.rs test_migrations_idempotent: assert source + remote_id columns + indexes (AC#8)
+- library.rs test_source_filter: insert local + plex row, assert plex filter works (AC#9)
+<!-- SECTION:PLAN:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added source/remote_id columns to the library table with idempotent migrations following the existing column-presence pattern. Updated Track model, row_to_track, all SELECT statements across library/favorites/queue/playlists, and library_get_all command. All 817 tests pass.
+<!-- SECTION:FINAL_SUMMARY:END -->

crates/mt-tauri/src/commands/queue.rs

@@ -1030,6 +1030,8 @@ mod tests {
             file_ctime_ns: None,
             file_inode: None,
             content_hash: None,
+            source: "local".to_string(),
+            remote_id: None,
         };
 
         let response = PlayContextResponse {
@@ -1081,6 +1083,8 @@ mod tests {
             file_ctime_ns: None,
             file_inode: None,
             content_hash: None,
+            source: "local".to_string(),
+            remote_id: None,
         };
 
         let response = PlayContextResponse {

crates/mt-tauri/src/db/favorites.rs

@@ -20,7 +20,7 @@ pub(crate) fn get_favorites(
                 l.track_number, l.track_total, l.disc_number, l.disc_total, l.date, l.genre,
                 l.duration, l.file_size, l.play_count, l.last_played, l.added_date,
                 l.missing, l.last_seen_at, l.file_mtime_ns, l.file_inode, l.content_hash,
-                f.timestamp as favorited_date
+                l.source, l.remote_id, f.timestamp as favorited_date
          FROM favorites f
          JOIN library l ON f.track_id = l.id
          ORDER BY f.timestamp ASC
@@ -49,7 +49,8 @@ pub(crate) fn get_top_25(conn: &Connection) -> DbResult<Vec<Track>> {
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library
          WHERE play_count > 0
          ORDER BY play_count DESC, last_played DESC
@@ -76,7 +77,8 @@ pub(crate) fn get_recently_played(
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library
          WHERE last_played IS NOT NULL
            AND last_played >= datetime('now', ?)
@@ -100,7 +102,8 @@ pub(crate) fn get_recently_added(conn: &Connection, days: i64, limit: i64) -> Db
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library
          WHERE added_date IS NOT NULL
            AND added_date >= datetime('now', ?)

crates/mt-tauri/src/db/library.rs

@@ -37,6 +37,10 @@ pub(crate) fn row_to_track(row: &Row) -> rusqlite::Result<Track> {
         play_count: row.get::<_, Option<i64>>("play_count")?.unwrap_or(0),
         missing: row.get::<_, Option<i64>>("missing")?.unwrap_or(0) != 0,
         last_seen_at: row.get("last_seen_at")?,
+        source: row
+            .get::<_, String>("source")
+            .unwrap_or_else(|_| "local".to_string()),
+        remote_id: row.get("remote_id").unwrap_or(None),
     })
 }
 
@@ -55,6 +59,8 @@ pub struct LibraryQuery {
     pub offset: i64,
     /// CSV of prefix words to strip for text sort ordering (e.g. "the,a,an")
     pub ignore_words: Option<String>,
+    /// When Some, appends `AND source = ?` to filter by track source ('local' or 'plex')
+    pub source_filter: Option<String>,
 }
 
 impl LibraryQuery {
@@ -106,6 +112,11 @@ fn build_library_where(query: &LibraryQuery) -> (String, Vec<Box<dyn rusqlite::T
         params_vec.push(Box::new(year_to));
     }
 
+    if let Some(source) = &query.source_filter {
+        conditions.push("source = ?");
+        params_vec.push(Box::new(source.clone()));
+    }
+
     // Always filter out missing tracks from library view
     conditions.push("(missing = 0 OR missing IS NULL)");
 
@@ -135,7 +146,8 @@ pub(crate) fn get_all_tracks(
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library
          {}
          ORDER BY {} {}{}
@@ -330,7 +342,8 @@ pub(crate) fn find_tracks_by_artist_title(
     let sql = "SELECT id, filepath, title, artist, album, album_artist,
             track_number, track_total, disc_number, disc_total, date, genre,
             duration, file_size, play_count, last_played, added_date,
-            missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+            missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+            source, remote_id
      FROM library
      WHERE (missing = 0 OR missing IS NULL)
        AND title = ? COLLATE NOCASE
@@ -365,7 +378,8 @@ pub(crate) fn get_track_by_id(conn: &Connection, track_id: i64) -> DbResult<Opti
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library WHERE id = ?",
     )?;
 
@@ -383,7 +397,8 @@ pub(crate) fn get_track_by_filepath(conn: &Connection, filepath: &str) -> DbResu
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library WHERE filepath = ?",
     )?;
 
@@ -961,7 +976,8 @@ pub(crate) fn get_missing_tracks(conn: &Connection) -> DbResult<Vec<Track>> {
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library WHERE missing = 1 ORDER BY title ASC",
     )?;
 
@@ -1001,7 +1017,8 @@ pub(crate) fn find_missing_track_by_inode(
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library WHERE file_inode = ? AND missing = 1 LIMIT 1",
     )?;
 
@@ -1022,7 +1039,8 @@ pub(crate) fn find_missing_track_by_content_hash(
         "SELECT id, filepath, title, artist, album, album_artist,
                 track_number, track_total, disc_number, disc_total, date, genre,
                 duration, file_size, play_count, last_played, added_date,
-                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash
+                missing, last_seen_at, file_mtime_ns, file_ctime_ns, file_inode, content_hash,
+                source, remote_id
          FROM library WHERE content_hash = ? AND missing = 1 LIMIT 1",
     )?;
 
@@ -3666,4 +3684,31 @@ mod tests {
         assert_eq!(first.artist.as_deref(), Some("Arcade Fire"));
         assert_eq!(second.artist.as_deref(), Some("The Decemberists"));
     }
+
+    #[test]
+    fn test_source_filter() {
+        let conn = setup_test_db();
+
+        conn.execute(
+            "INSERT INTO library (filepath, title, source, missing) VALUES ('/local.mp3', 'Local Track', 'local', 0)",
+            [],
+        )
+        .unwrap();
+        conn.execute(
+            "INSERT INTO library (filepath, title, source, remote_id, missing) VALUES ('/plex/12345', 'Plex Track', 'plex', '12345', 0)",
+            [],
+        )
+        .unwrap();
+
+        let query = LibraryQuery {
+            source_filter: Some("plex".to_string()),
+            limit: 100,
+            ..Default::default()
+        };
+        let result = get_all_tracks(&conn, &query).unwrap();
+        assert_eq!(result.items.len(), 1);
+        assert_eq!(result.items[0].title, Some("Plex Track".to_string()));
+        assert_eq!(result.items[0].remote_id, Some("12345".to_string()));
+        assert_eq!(result.items[0].source, "plex");
+    }
 }

crates/mt-tauri/src/db/models.rs

@@ -5,6 +5,10 @@
 
 use serde::{Deserialize, Serialize};
 
+fn default_source() -> String {
+    "local".to_string()
+}
+
 /// Track metadata from the library table
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct Track {
@@ -31,6 +35,9 @@ pub struct Track {
     pub play_count: i64,
     pub missing: bool,
     pub last_seen_at: Option<i64>,
+    #[serde(default = "default_source")]
+    pub source: String,
+    pub remote_id: Option<String>,
 }
 
 /// Track metadata for insertion (without id and computed fields)

crates/mt-tauri/src/db/playlists.rs

@@ -94,7 +94,8 @@ pub(crate) fn get_playlist(
                 l.track_number, l.track_total, l.disc_number, l.disc_total,
                 l.date, l.genre, l.duration, l.file_size,
                 l.play_count, l.last_played, l.added_date, l.missing, l.last_seen_at,
-                l.file_mtime_ns, l.file_ctime_ns, l.file_inode, l.content_hash, pi.position, pi.added_at
+                l.file_mtime_ns, l.file_ctime_ns, l.file_inode, l.content_hash,
+                l.source, l.remote_id, pi.position, pi.added_at
          FROM playlist_items pi
          JOIN library l ON pi.track_id = l.id
          WHERE pi.playlist_id = ?

crates/mt-tauri/src/db/queue.rs

@@ -14,7 +14,8 @@ pub(crate) fn get_queue(conn: &Connection) -> DbResult<Vec<QueueItem>> {
                 l.track_number, l.track_total, l.disc_number, l.disc_total,
                 l.date, l.genre, l.duration, l.file_size,
                 l.play_count, l.last_played, l.added_date, l.missing, l.last_seen_at,
-                l.file_mtime_ns, l.file_ctime_ns, l.file_inode, l.content_hash
+                l.file_mtime_ns, l.file_ctime_ns, l.file_inode, l.content_hash,
+                l.source, l.remote_id
          FROM queue q
          LEFT JOIN library l ON q.filepath = l.filepath
          ORDER BY q.id",
@@ -50,6 +51,10 @@ pub(crate) fn get_queue(conn: &Connection) -> DbResult<Vec<QueueItem>> {
             play_count: row.get::<_, Option<i64>>("play_count")?.unwrap_or(0),
             missing: row.get::<_, Option<i64>>("missing")?.unwrap_or(0) != 0,
             last_seen_at: row.get("last_seen_at")?,
+            source: row
+                .get::<_, String>("source")
+                .unwrap_or_else(|_| "local".to_string()),
+            remote_id: row.get("remote_id").unwrap_or(None),
         };
 
         items.push(QueueItem { position, track });

crates/mt-tauri/src/db/queue_props_test.rs

@@ -41,7 +41,9 @@ mod tests {
                 last_played TEXT,
                 play_count INTEGER DEFAULT 0,
                 missing INTEGER DEFAULT 0,
-                last_seen_at TEXT
+                last_seen_at TEXT,
+                source TEXT NOT NULL DEFAULT 'local',
+                remote_id TEXT
             )",
             [],
         )