Справочник по базе данных

Для кого: Пользователи и разработчики, которым важно понимать локальное хранение SQLite. Задача: Объяснить назначение баз без полного дампа схемы. Тип: Справочник

При выборе library.sqlite открывается один комплект каталога схемы v7:

Хранилище	Файл	Создание	Содержимое
Core	library.sqlite	обязательно	идентификатор каталога, треки, файловые теги, контракты, скалярные значения SONARA, данные MAEST, оценки классификаторов, отметки, обратная связь, FTS и настройки
Artifacts	library.artifacts.sqlite	обязательно	отдельные таблицы эмбеддингов MAEST/MERT/MuQ/CLAP и SONARA, временные ряды SONARA и отпечатки
Evaluation	library.evaluation.sqlite	необязательно	поисковые сессии, события результатов, запуски калибровки и настройки оценки

Для нового пути Core и Artifacts создаются вместе и получают общий catalog_uuid. Открытие прерывается, если одного из обязательных файлов нет, его схема неверна или он принадлежит другому каталогу. Простое определение пути Evaluation не создаёт файл: это делает только нуждающийся в нём сценарий оценки с проверкой того же каталога.

Это новая рабочая схема v7, а не миграция. Базы не v7 отклоняются с требованием чистой v7. Удалённых команд migrate-v7 и migrate-schema-v7 в текущем CLI нет.

Данные Core

Core содержит:

• library_catalog и contracts для идентификатора каталога и неизменяемых контрактов анализа;
• tracks и file_tags для идентичности файла, пути, технических сведений и метаданных Mutagen;
• актуальные скалярные и компактные векторные значения в sonara;
• жанры и синкопированность MAEST в maest_scores;
• результаты опубликованных классификаторов в classifier_scores;
• отметки «нравится», обратную связь по парам и переходам, FTS и настройки.

Идентичность трека составная: catalog_uuid, track_id, track_uuid и content_generation. Запросы на изменение передают ожидаемую идентичность, поэтому устаревший клиент не может незаметно изменить заменённый или повторно просканированный трек. Путь хранится в tracks.file_path.

Данные Artifacts

В обязательной базе Artifacts находятся отдельные таблицы:

• maest_embeddings — эмбеддинги MAEST;
• mert_embeddings — эмбеддинги MERT;
• muq_embeddings — эмбеддинги MuQ;
• clap_embeddings — эмбеддинги CLAP;
• sonara_similarity_embeddings — эмбеддинги похожести SONARA;
• sonara_timeline — временные данные SONARA;
• sonara_fingerprints — аудиоотпечатки SONARA.

Обычные ответы по трекам возвращают компактные сводки и признаки наличия. Явный маршрут GET /api/tracks/{track_id}/sonara-timeline загружает актуальные подписанные временные данные.

Состояние релиза SONARA

Текущий контракт фиксирует SONARA 0.2.9, схему результата 4, режим playlist, частоту 22050, диапазон BPM 70..180 и ревизию признаков проекта 6. У него четыре независимых результата: core, timeline, embedding и fingerprint.

До записи нового релиза выполните:

dj-sim prepare-sonara-release --db .\data\library.sqlite --backup-dir .\backup --confirm "PREPARE SONARA RELEASE"

Команда сама определяет идентичность загруженной среды. Передать свой хеш релиза или выбрать подмножество результатов нельзя. Она проверяет пару резервных копий Core и Artifacts и выполняет упорядоченную активацию с журналом-квитанцией. После прерывания процесс можно продолжить, а несогласованное состояние блокируется. Предыдущие строки SONARA и зависимые оценки классификаторов удаляются, чтобы релизы не смешивались. Схему старой базы команда не мигрирует.

Состояние классификаторов

Рабочая среда принимает манифест версии 2. Версия 1 и манифесты без версии блокируются с требованием переобучить и заново опубликовать профиль. Текущие файлы в models/classifiers/ всё ещё используют версию 1, поэтому расчёт невозможен до нового обучения и публикации. Сброс и расчёт ограничены ключом классификатора и сохраняют оценки других профилей.

Границы записи

• Scan, Refresh Tags, анализ, сброс, очистка, отметки, классификаторы, обратная связь и применение переноса записывают SQLite.
• Применение переноса меняет только tracks.file_path и не перемещает аудио.
• Очистка удаляет строки Core, соответствующие строки Artifacts и существующие данные Evaluation, но не аудио.
• Сброс удаляет только активные результаты выбранного семейства и зависимые оценки SONARA.
• Audio Dedup удаляет строки базы только для файлов, которые действительно удалены.
• Разрушительные операции с C:\db\volumes.sqlite или другой реальной библиотекой требуют явного разрешения и проверенной резервной копии.

Резервное копирование

Храните Core и Artifacts вместе. Добавляйте Evaluation, если он существует. Перед разрушительным обслуживанием реальной фонотеки создайте копию всего существующего комплекта, проверьте её, а после операции проверьте целостность рабочих баз.