Implement automatic database-level genre migration

- Override Library._make_table() to detect when genres column is added
- Automatically migrate comma-separated genres to list format on first run
- Try multiple separators: ", ", "; ", " / " for legacy compatibility
- Show progress every 100 items to avoid CLI spam for large libraries
- Write changes to both database and media files during migration
- Remove manual migrate command (migration is now automatic and mandatory)
- Simplify correct_list_fields() to only sync genre ↔ genres fields
- Update all tests for list-based genres (lastgenre, musicbrainz, autotag)
- Update documentation to reflect automatic migration behavior

Addresses maintainer feedback on PR beetbox#6169. Migration runs once when the
database schema is updated, ensuring all users transition to multi-value
genres seamlessly without manual intervention.

Author: jfot-cpu

beets/autotag/__init__.py

@@ -166,37 +166,7 @@ def ensure_first_value(single_field: str, list_field: str) -> None:
         elif list_val:
             setattr(m, single_field, list_val[0])
 
-    def migrate_legacy_genres() -> None:
-        """Migrate comma-separated genre strings to genres list.
-
-        For users upgrading from previous versions, their genre field may
-        contain comma-separated values (e.g., "Rock, Alternative, Indie").
-        This migration splits those values into the genres list on first access,
-        avoiding the need to reimport the entire library.
-        """
-        genre_val = getattr(m, "genre", "")
-        genres_val = getattr(m, "genres", [])
-
-        # Only migrate if genres list is empty and genre contains separators
-        if not genres_val and genre_val:
-            # Try common separators used by lastgenre and other tools
-            for separator in [", ", "; ", " / "]:
-                if separator in genre_val:
-                    # Split and clean the genre string
-                    split_genres = [
-                        g.strip()
-                        for g in genre_val.split(separator)
-                        if g.strip()
-                    ]
-                    if len(split_genres) > 1:
-                        # Found a valid split - populate genres list
-                        setattr(m, "genres", split_genres)
-                        # Clear genre so ensure_first_value sets it correctly
-                        setattr(m, "genre", "")
-                        break
-
     ensure_first_value("albumtype", "albumtypes")
-    migrate_legacy_genres()
     ensure_first_value("genre", "genres")
 
     if hasattr(m, "mb_artistids"):

beets/library/library.py

@@ -5,14 +5,19 @@
 import platformdirs
 
 import beets
-from beets import dbcore
+from beets import dbcore, logging, ui
+from beets.autotag import correct_list_fields
 from beets.util import normpath
 
 from .models import Album, Item
 from .queries import PF_KEY_DEFAULT, parse_query_parts, parse_query_string
 
 if TYPE_CHECKING:
-    from beets.dbcore import Results
+    from collections.abc import Mapping
+
+    from beets.dbcore import Results, types
+
+log = logging.getLogger("beets")
 
 
 class Library(dbcore.Database):
@@ -125,20 +130,109 @@ def items(self, query=None, sort=None) -> Results[Item]:
         return self._fetch(Item, query, sort or self.get_default_item_sort())
 
     # Convenience accessors.
-    def get_item(self, id_: int) -> Item | None:
+
+    def get_item(self, id):
         """Fetch a :class:`Item` by its ID.
 
         Return `None` if no match is found.
         """
-        return self._get(Item, id_)
+        return self._get(Item, id)
 
-    def get_album(self, item_or_id: Item | int) -> Album | None:
+    def get_album(self, item_or_id):
         """Given an album ID or an item associated with an album, return
         a :class:`Album` object for the album.
 
         If no such album exists, return `None`.
         """
-        album_id = (
-            item_or_id if isinstance(item_or_id, int) else item_or_id.album_id
+        if isinstance(item_or_id, int):
+            album_id = item_or_id
+        else:
+            album_id = item_or_id.album_id
+        if album_id is None:
+            return None
+        return self._get(Album, album_id)
+
+    # Database schema migration.
+
+    def _make_table(self, table: str, fields: Mapping[str, types.Type]):
+        """Set up the schema of the database, and migrate genres if needed."""
+        with self.transaction() as tx:
+            rows = tx.query(f"PRAGMA table_info({table})")
+        current_fields = {row[1] for row in rows}
+        field_names = set(fields.keys())
+
+        # Check if genres column is being added to items table
+        genres_being_added = (
+            table == "items"
+            and "genres" in field_names
+            and "genres" not in current_fields
+            and "genre" in current_fields
+        )
+
+        # Call parent to create/update table
+        super()._make_table(table, fields)
+
+        # Migrate genre to genres if genres column was just added
+        if genres_being_added:
+            self._migrate_genre_to_genres()
+
+    def _migrate_genre_to_genres(self):
+        """Migrate comma-separated genre strings to genres list.
+
+        This migration runs automatically when the genres column is first
+        created in the database. It splits comma-separated genre values
+        and writes the changes to both the database and media files.
+        """
+        items = list(self.items())
+        migrated_count = 0
+        total_items = len(items)
+
+        if total_items == 0:
+            return
+
+        ui.print_(f"Migrating genres for {total_items} items...")
+
+        for index, item in enumerate(items, 1):
+            genre_val = item.genre or ""
+            genres_val = item.genres or []
+
+            # Check if migration is needed
+            needs_migration = False
+            split_genres = []
+            if not genres_val and genre_val:
+                for separator in [", ", "; ", " / "]:
+                    if separator in genre_val:
+                        split_genres = [
+                            g.strip()
+                            for g in genre_val.split(separator)
+                            if g.strip()
+                        ]
+                        if len(split_genres) > 1:
+                            needs_migration = True
+                            break
+
+            if needs_migration:
+                migrated_count += 1
+                # Show progress every 100 items
+                if migrated_count % 100 == 0:
+                    ui.print_(
+                        f"  Migrated {migrated_count} items "
+                        f"({index}/{total_items} processed)..."
+                    )
+                # Migrate using the same logic as correct_list_fields
+                correct_list_fields(item)
+                item.store()
+                # Write to media file
+                try:
+                    item.try_write()
+                except Exception as e:
+                    log.warning(
+                        "Could not write genres to {}: {}",
+                        item.path,
+                        e,
+                    )
+
+        ui.print_(
+            f"Migration complete: {migrated_count} of {total_items} items "
+            f"updated with comma-separated genres"
         )
-        return self._get(Album, album_id) if album_id else None

beets/ui/commands/__init__.py

@@ -24,7 +24,6 @@
 from .help import HelpCommand
 from .import_ import import_cmd
 from .list import list_cmd
-from .migrate import migrate_cmd
 from .modify import modify_cmd
 from .move import move_cmd
 from .remove import remove_cmd
@@ -53,7 +52,6 @@ def __getattr__(name: str):
     HelpCommand(),
     import_cmd,
     list_cmd,
-    migrate_cmd,
     modify_cmd,
     move_cmd,
     remove_cmd,