The read cache is a SQLite database that replicates the metadata in music_source_dir
. The read
cache exists solely to improve performance: it can be read from far more performantly than the
music_source_dir
can.
The read cache does not have any state of its own. All of the data in the read cache is replicated
from the music_source_dir
. Hence, we never write directly to the read cache. Instead, we always
write directly to the source files and then trigger the cache update sequence. The cache update
sequence updates the cache to match the source directory's state.
Note
To better understand how the read cache fits into Rosé, we recommend reading Architecture.
Assuming you only modify your music library through Rosé, the cache will always remain up to date, since Rosé triggers a cache update whenever it is aware of an update to the source directory.
However, that assumption does not hold. If changes are made directly to the source directory, and Rosé is not "informed," Rosé's cache will contain the previous state of the source directory. We call this a cache drift.
This is problematic because Rosé may attempt to read files that no longer exist or display old metadata. Thus, we should inform Rosé whenever a change is made to the source directory.
A cache update can be performed manually with the rose cache update
command. In this command, Rosé
will identify any files that changed and update the read cache accordingly. In other words, this
command informs Rosé that something changed in the source directory.
For performance reasons, the rose cache update
command only checks files with a different Last
Modified (mtime) from the last cache update. To disable this behavior and recheck every file, pass
the --force/-f
flag.
It would be annoying if you had to run rose cache upate
by hand after each metadata change. Rosé
thus automatically updates the cache in response to changes made through Rosé. Any updates made
through the virtual filesystem or command line automatically trigger a cache update for the changed
files. Rosé will also update the cache when the virtual filesystem is mounted.
However, even with that improvement, if you directly change the source directory with a tool that
isn't Rosé, the cache will not automatically update in response. If you make all edits through Rosé,
then this isn't a problem! But for users with other tools that directly edit the source directory,
Rosé provides the rose cache watch
command, which runs a watcher that listens for file update
events in the source directory. This watcher will trigger a cache update whenever a file in the
source directory changes.
When Rosé detects that:
- Rosé has been upgraded to a new version,
- Cache-relevant configuration options have changed,
- Or the cache database schema has changed,
Rosé will delete the read cache and rebuild it from scratch. A full cache rebuild is fairly performant, though an order of magnitude slower than a cache scan that results in no changes.
Deleting the read cache does not result in any loss of data and is a viable solution if your cache
ends up in a really bad state that rose cache update --force
does not resolve. This should not be
necessary normally, but may occur from a surprise bug.