MusicBrainz Local Database

MusicBrainz is the source of all music metadata in Shanty: artist information, album listings, track listings, and release data. By default, Shanty queries the MusicBrainz API over the internet, which is rate-limited to 1 request every 1.1 seconds.

Importing the MusicBrainz database locally eliminates this bottleneck for most lookups.

What this does

The import downloads a full copy of the MusicBrainz database (as JSON dumps) and loads it into a local SQLite database on your machine. When Shanty needs to look up an artist's discography, release track listings, or recording details, it checks the local database first. If the data is found locally, the response is instant. If not (for example, very new releases), it falls back to the remote API.

Why you might want this

Without the local database, browsing a new artist's full discography requires many API calls (one per release group, one per release to get track listings). With the rate limit, loading an artist with 15 albums can take 30-60 seconds.

With the local database, the same operation completes in under a second.

If you are casually using Shanty for a few artists, the caching system works well enough without the local database. But if you frequently browse and add new artists, the local database makes the experience dramatically faster.

Requirements

Download size: approximately 24 GB (compressed JSON dumps from MusicBrainz)
Database size: approximately 16 GB (the resulting SQLite database)
Disk type: SSD strongly recommended for best performance. On an SSD, artist pages load in under a second. On a spinning hard drive, the database still works and is a big improvement over the API (a few seconds per page load instead of 30-60 seconds), but you will notice the difference compared to SSD.
Time: 12-24 hours for the initial import, depending on your hardware and disk speed.
Disk space total: You need roughly 40 GB free during import (dumps + database). After import, you can delete the dump files to reclaim the 24 GB.

How to set up via the web UI

Open the Shanty web UI and go to Settings.
Scroll to the MusicBrainz Database section.
Click Import.
Shanty downloads the dump files and imports them. Progress is shown on the Dashboard.

You can continue using Shanty while the import runs. It will use the remote API until the import completes.

How to set up via the CLI

If you prefer the command line (or want to run the import on a more powerful machine):

# Inside Docker
docker compose exec shanty ./shanty mb-import --download

# From source
cargo run --release --bin shanty -- mb-import --download

Options:

--download -- Download fresh dump files from metabrainz.org before importing. Without this flag, the import looks for existing dump files in the data directory.
--data-dir /path/to/dumps -- Custom directory for dump files. Defaults to {data_dir}/mb-dumps.

The database is created at {data_dir}/shanty-mb.db by default. You can override this with the musicbrainz.local_db_path config option.

Automatic weekly updates

MusicBrainz publishes new database dumps regularly. You can configure Shanty to automatically re-download and re-import them:

musicbrainz:
  auto_update: true

When enabled, Shanty checks weekly for new dumps and runs the import in the background if a newer dump is available. The existing local database continues to serve queries during the update.

The hybrid approach

Shanty uses what it calls a "hybrid fetcher":

Local database is checked first for any MusicBrainz lookup (artist info, release groups, track listings, etc.).
Remote API is used as a fallback when data is not in the local database (new releases added after the last import, for example).
Cache is used for data that was fetched from the remote API, so repeated lookups do not hit the rate limit.

This means you get the best of both worlds: instant lookups for the vast majority of music that exists in the database dumps, and up-to-date data for newly released music via the API.

Configuration options

Option	Default	Description
`musicbrainz.local_db_path`	`{data_dir}/shanty-mb.db`	Path to the local SQLite database
`musicbrainz.auto_update`	`false`	Automatically re-import dumps weekly

4.3 KiB Raw Permalink Blame History