Architecture de la base de données
Cette page décrit comment Tune range ses données : moteurs pris en charge, migrations, grandes familles de tables, recherche plein texte et sauvegardes. L'emplacement du fichier et l'activation de PostgreSQL sont décrits dans Configuration.
Deux moteurs, un seul actif
- SQLite est le moteur par défaut. Il est compilé dans le programme : rien à installer, rien à régler. La base tient dans un seul fichier,
tune.db. - PostgreSQL est une option, présente dans les versions publiées pour Windows, macOS et Linux (sauf l'image Docker et la version
aarch64-musl). - Le moteur se choisit au démarrage : une adresse
postgres://oupostgresql://sélectionne PostgreSQL, sinon Tune utilise SQLite. Un seul moteur est ouvert à la fois. - Le reste du serveur passe par une interface commune aux deux moteurs.
Migrations
- Le schéma évolue par migrations numérotées, appliquées automatiquement au démarrage. Pendant ce temps, le serveur répond déjà sur son port et l'indique.
- SQLite : les migrations appliquées sont notées dans une table
_migrations(version, nom, date). Tune n'applique que celles qui manquent. Une passe de vérification, sans effet si tout est en place, s'exécute ensuite à chaque démarrage. - PostgreSQL a sa propre série de migrations SQL, écrite pour lui et suivie dans une table
schema_version. - Il n'y a pas de migration inverse. Si la base a été créée par une version plus récente de Tune, le serveur l'écrit dans le journal.
Tables principales
La base SQLite compte une soixantaine de tables. Les domaines sont les mêmes avec PostgreSQL.
| Domaine | Tables | Contenu |
|---|---|---|
| Bibliothèque | artists, albums, tracks, track_credits | Artistes, albums (année, genre, pochette, format, fréquence, profondeur), pistes (chemin du fichier, durée, format, ISRC, empreinte audio, repères CUE), crédits par rôle |
| Métadonnées | track_metadata, album_metadata, metadata_proposals, lyrics_cache | Métadonnées enrichies, propositions de correction, paroles en cache |
| Classement | tags, item_tags, favorites, album_ratings, hidden_items | Étiquettes, favoris (par profil), notes, éléments masqués |
| Lecture | zones, queue_items | Zones (type de sortie, appareil, volume, groupe, décalage de synchronisation, mode DSD), file d'attente de chaque zone |
| Playlists | playlists, playlist_tracks, smart_playlists, smart_collections | Playlists (pistes locales ou de services), playlists et collections intelligentes |
| Radios et podcasts | radio_stations, radio_favorites, podcast_subscriptions | Stations, favoris, abonnements |
| Services | streaming_auth, streaming_favorites, offline_cache | Connexions aux services, favoris des services, cache hors ligne |
| Profils et réglages | profiles, settings | Profils, réglages sous forme clé-valeur |
| Historique | listen_history, playback_history | Écoutes |
| Réseau | network_mounts, media_servers, ignored_devices | Partages réseau, serveurs UPnP, appareils ignorés |
SQLite en détail
- Mode de journal WAL : la lecture et l'écriture se font en parallèle. Les clés étrangères sont vérifiées.
- Une connexion d'écriture et trois connexions de lecture seule.
- Si la base se trouve sur un système de fichiers réseau ou FUSE (NFS, SMB, exFAT, NTFS…), Tune repasse au journal classique et le signale dans le journal : le mode WAL n'y est pas fiable. Préférez un disque local.
- Recherche plein texte : trois index FTS5 (artistes, albums, pistes), tenus à jour automatiquement. Ils ignorent les accents. Une fonction
unaccent()ajoutée par Tune fait de même pour les autres recherches. Les index se reconstruisent parPOST /api/v1/system/database/rebuild-fts.
PostgreSQL en détail
- Version conseillée : PostgreSQL 16. La 15 fonctionne aussi ; la 14 n'a pas été testée.
- L'extension
unaccentest nécessaire. Elle est fournie avec PostgreSQL 16 ; sous PostgreSQL 15, elle fait partie du paquetcontrib. - La recherche plein texte passe par des colonnes
tsvectoret des index GIN. - Le serveur ouvre jusqu'à 16 connexions.
Passer de SQLite à PostgreSQL
- Dans l'interface : Réglages › Système › Base de données › Migrer vers PostgreSQL (niveau Expert). Tune crée la base PostgreSQL si elle n'existe pas, copie toutes les tables, applique les migrations PostgreSQL, enregistre l'adresse, puis redémarre sur PostgreSQL.
- Tune ne supprime pas la base SQLite d'origine.
- L'outil en ligne de commande propose aussi
tune db migrate-to-postgres, mais il ne copie que les tables de base : préférez l'interface.
Sauvegardes
- Avec SQLite, une sauvegarde se crée à la demande, depuis Réglages › Système › Base de données ou par
POST /api/v1/system/backups. Tune la range dans un dossierbackupsà côté de la base et garde les cinq plus récentes. - Tune fait aussi une copie de sécurité avant d'importer une base.
- Avec PostgreSQL, utilisez les outils de PostgreSQL, comme
pg_dump.
Voir aussi
- Configuration : emplacement de la base, variables, activation de PostgreSQL
- Architecture
- Guide technique