musicbrainz-server: the Perl and React front end to the MusicBrainz database

A web frontend in front of a community owned database

MusicBrainz Server is the web frontend to the MusicBrainz Database and is accessible at musicbrainz.org. The project description is short, and it covers three things: the website, the API, and database tools.

What sits behind it is unusual. MusicBrainz is a user-maintained open community that collects music metadata and makes it available to the public in the form of a relational database. The emphasis on user-maintained is the important word. This is not a company catalogue that was exported into a schema; it is a database where the editorial process is a wiki, the correction process is a queue, and the release process is a replication event.

That has direct consequences for anyone reading the code. The schema is not a normalised model of albums and artists designed by a database architect, it is the accumulated result of a community deciding what to record about a release, and a lot of the structure exists to accommodate real world mess such as the same release appearing with different track listings in different countries. The primary key is a surrogate identifier rather than a natural one, and the tables carry fields for the edit history and the relationships between entities rather than only the entities themselves.

The three surfaces named in the description, website, API and database tools, are the three ways a person or a program touches that data. The API is what makes the project a foundation for other tools, and the database tools are what make it usable by organisations that want their own copy of the data.

Perl and Catalyst underneath, React and Babel on top

The repository layout is the clearest evidence of the architecture, because it shows three generations of web development coexisting in one tree.

The Perl side is visible in lib/, admin/, bin/, script/, t/ for the test suite, the cpanfile and cpanfile.snapshot for dependency management, and app.psgi, which is the PSGI entry point that says this is a PSGI application. The presence of a .perlcriticrc file tells you the Perl code is linted, and po/ and the translation tooling suggest the interface is localised. The topics list includes catalyst, which names the web framework the Perl side is built on.

The JavaScript side is equally visible. There is a webpack/ directory, a babel.config.cjs, an eslint.config.mjs alongside a legacy .eslintrc.unfixed.yaml, a .flowconfig, flow-typed/ with flow-typed.config.json, and a yarn.lock with a .yarnrc.yml. The package.json is explicit about what it is, described as package.json for keeping track of musicbrainz-server nodejs dependencies. The Flow type checker and the Babel setup are the older half of the JavaScript story, and the React dependencies such as @floating-ui/react, babel-plugin-react-compiler and the several @babel/plugin-transform-react-* packages are the newer half.

The most telling entries are the git dependencies. jed is pulled from a fork on GitHub, and knockout, knockout-arraytransforms are pinned to specific commits of forks rather than to published versions. That is the signature of a project where the front end had to be modified in ways upstream would not accept, and the fork became the only workable path. It is not a criticism so much as a record of what a decade of maintenance does to a dependency graph.

Other entries point at what the front end does. leaflet and leaflet.markercluster are the map, so the site draws artist and venue geography on an OpenStreetMap base. @sentry/browser and @sentry/node are the error reporting. filesize is for the release size display, and canonical-json and generic-diff are the ingredients of a diff view, which is what a wiki-style edit history needs.

The prerequisites are recent, and the install lives in INSTALL.md

The general prerequisites are listed in the README and they are not old ones.

Ubuntu or Debian, or some other Unix-like operating system at your own risk. Node at least version 24. Perl at least version 5.42. PostgreSQL at least version 18.

The full installation instructions are in INSTALL.md, with INSTALL-MASTER.md alongside it for the multi instance setup, and the tree also carries a docker/ directory and a.dockerignore, so a containerised path exists as well. HACKING.md, HACKING-IMG.md, HACKING-PROD.md and MAINTENANCE.md split the operational documentation by audience.

Those version floors are worth pausing on, because they tell you what the project is keeping pace with. A Perl requirement of 5.42 means the code uses recent language features, and a PostgreSQL floor of 18 means the SQL and the schema exploit modern server behaviour. The consequence for an adopter is that you cannot deploy this on a long term supported distribution's default versions without a third party repository, and the base distribution choice is Ubuntu or Debian by default.

The package.json is worth a look because it is honest about being a dependency manifest rather than a published package, with the version pinned at 0.0.0 and the description spelling out its purpose.

{
  "name": "musicbrainz-server",
  "version": "0.0.0",
  "description": "package.json for keeping track of musicbrainz-server nodejs dependencies",
  "license": "GPL-2.0-or-later"
}

The version 0.0.0 is not a placeholder mistake, it is a signal that this package is not distributed. It exists to pin the front end dependencies for the build.

Breaking changes are announced, which tells you how the data model moves

The README has a short section that deserves more attention than it gets, and it is about breaking changes rather than features.

Breaking changes to the database schema or the API and web service will be announced on the project blog, and the recommendation is to follow it.

That is the whole story of MusicBrainz data in three sentences. The schema is not frozen, and neither is the API contract, and both change in ways that break consumers. The blog category is a breaking changes one under the musicbrainz tag.

The repository reflects that with two files you will not find in a typical web application. There is upgrade.json, which describes the schema migration steps, and upgrade.sh, which applies them. There is also an entities.json and an entities.mjs pair, which is a machine readable description of the entities and their relationships, and a musicbrainz.yml configuration file at the root.

For an adopter this has two consequences. The first is that the data is versioned separately from the code, so a schema upgrade and a server upgrade are related but distinct operations, and a deployment has to decide which order to do them in. The second is that anything you build on the API has to be prepared for the contract to move, which is a different commitment from the one you make when you depend on a library.

The same caution applies to the SQL directly. A significant number of MusicBrainz users run their own queries against their own replica, and the entity model, with its surrogate identifiers and its many to many relationship tables, is not a schema you can refactor lightly.

Two licence statements that need reconciling

The licence is stated in the README in one line, and the repository metadata says something different.

The README says MusicBrainz Server is released under the GPLv2 or later, and points at the license notice in COPYING.md. The package.json agrees, declaring GPL-2.0-or-later. The repository metadata, however, records the licence as a custom one that GitHub cannot classify, with a note to see the LICENSE file.

That is a discrepancy worth resolving before you rely on it, and resolving it means reading COPYING.md and the LICENSE file, which is what the two sources point you to. It is not unusual for a project with a long history to have a LICENSE file carrying additional terms alongside a COPYING file, and it is not unusual for the two to have drifted. The safe reading is that the copyleft obligation applies, in some form, and that the exact terms are in those files rather than in the one line summary.

What you can say without any doubt is that this is a copyleft project and that a derived work distributed to users carries obligations. For a team planning to run the server as an internal service that is not distributed, the practical question is different and easier, and the obligation to publish modifications is largely not engaged. For a team planning to ship a product containing this code, the files need reading by someone who handles licence questions, and this article is not that.

The community expectations are visible in the contribution section too. Patches go to GitHub for review, the contributing guidelines are in CONTRIBUTING.md, and there is a separate RELEASING.md, which tells you that releasing this project is a documented, deliberate process rather than something that happens by tagging.

Where a metadata API is the wrong thing to run

Two honest cases for not choosing this, plus one for choosing it.

The first case is that you do not need MusicBrainz. If you want artist metadata for your own project, a smaller database or a set of web API clients may serve you, and running a Perl, Node, PostgreSQL and search stack to get it is a lot of surface area. The value of musicbrainz-server is that it is the canonical server, not that it is a good general purpose web application.

The second case is that you cannot accept a moving target. The API and the schema both change, and the changes are announced rather than hidden, which is good practice but still a change. A consumer that cannot be reworked when the contract moves has to freeze somewhere, and this project is not the place to freeze.

The third case is scale mismatch in the other direction. A community maintained database with a release replication process, a search index, an edit queue and a moderation workflow is built for a specific kind of operation, and running your own instance is a commitment with a specific shape.

Where it fits is the case the project is built for. If you want the canonical MusicBrainz data, with the canonical schema, and you intend to work within its update model rather than around it, then this is the implementation, and the surrounding community is the point. The IRC channel #metabrainz on irc.libera.chat is where that community lives, and the site, the documentation and the bug tracker sit at the links in the README.

Editorial conclusion

musicbrainz-server fits a developer who wants to read how a large, community maintained metadata service is actually built, with a real schema, real migrations, a real search index and a decade of accumulated decisions in it, and it fits a team that needs to run the reference MusicBrainz database and API. It does not fit a team looking for a lightweight API framework, because the Perl, Node and PostgreSQL stack is not something you adopt piecemeal, and it does not fit anyone who needs the schema to stay fixed, since a project with active users will eventually need to change it. Check three things before you commit. Check the version floor, because the requirements are recent: Node at least 24, Perl at least 5.42 and PostgreSQL at least 18. Check the schema rather than the code, because the repository carries an upgrade.json and an upgrade.sh that tell you how the database moves forward, and the breaking changes are announced on the project blog. And check the licence question carefully, because the README states GPLv2 or later and points at COPYING.md while GitHub itself classifies the repository licence as a custom one that it cannot classify, and those two statements need reconciling before you ship anything. The last push was on 2026-10-15 and the project is not archived.

Frequently asked questions

Official sources

1. Issues
2. metabrainz/musicbrainz-server on GitHub
3. Project website
4. README