Repository navigation
Database Architecture
Supernova utilizes SQLite3 running in WAL (Write-Ahead Logging) mode. This allows the server to handle concurrent read operations (like audio streaming to multiple devices) without locking up during write operations (like background library scanning or plugin tasks).
Tracks system users. Stores login credentials via bcrypt hashes. Passwords are theoretically safe even if the .db file is compromised.
Store library entities. They include musicbrainz_id for external API reconciliation and bio/image_url fields for UI richness.
The central hub for media.
-
Integrity:
file_pathis strictly enforced asUNIQUE NOT NULLto prevent scanning the same file multiple times. -
Foreign Keys: Enforces
ON DELETE CASCADEto thealbumstable. If an album is deleted, all tracks are purged from the DB automatically.
Because a track can have multiple artists (e.g., featured artists), and an album can be a collaboration, Supernova uses many-to-many junction tables:
-
track_artists: Mapstrack_id->artist_id. -
album_artists: Mapsalbum_id->artist_idwith a specificrole(e.g., primary, featured, producer).
Stores user favorites. Polymorphic mapping is handled via entity_type (track, album, artist, playlist) and entity_id.
Standard playlist implementation. playlist_tracks tracks the exact position of a song in the list.
An internal log of a user's listening history.
To ensure API responses return in milliseconds even with hundreds of thousands of tracks, Supernova applies critical indexes:
idx_tracks_album_ididx_tracks_file_pathidx_artists_nameidx_scrobbles_user_id_time
Supernova handles database migrations internally using the SQLite PRAGMA user_version. When the server starts, it checks this version and automatically applies delta SQL patches (e.g., migrating to version 4 to add file_modified_at or ignored_files).