instructions – MetaBrainz Blog

MusicBrainz database schema change release, 2026-05-11 (with upgrade instructions)

We’re happy to announce the release of our May 2026 database schema change now! Thanks to all who were patient during Monday’s downtime as we released everything to our production servers.

This is a fairly small database schema change release which mostly improves things behind the scenes. Of the schema change tickets, the only one that affects users directly is you are most likely to notice while you browse and edit in MusicBrainz is MBS-14092 (which allows adding series of series, for example for award series for podcasts).

Thanks to chaban, UltimateRiff and yyb987 for having reported bugs and suggested improvements, and thanks to jmrr83, salo.rock and wileyfoxyx for updating the translations.

A new release of MusicBrainz Docker is also available that matches this update of MusicBrainz Server. See the (amended) release notes for update instructions.

MusicBrainz database schema change release, 2025-05-19 (with upgrade instructions)

We’re happy to announce the release of our May 2025 database schema change now! Thanks to all who were patient during Monday’s downtime as we released everything to our production servers.

This is a fairly small database schema change release which mostly makes minor improvements and fixes small bugs. Of the schema change tickets, the one you are most likely to notice while you browse and edit in MusicBrainz is MBS-9253 (which makes it possible to change the order in which we display release groups, and mean EPs now sort before singles). MBS-13832 means releases which have PDF front images now also show the cover art on the sidebar, and MBS-13768 provides permanent links to mediums.

Thanks to Brownd, salo.rock and silentbird for having reported bugs and suggested improvements, and thanks to BenjaBarcos1, Echelon, Joax, Marc Riera, Michal77, onemanue, ozodbekmirzayev and salo.rock for updating the translations.

A new release of MusicBrainz Docker is also available that matches this update of MusicBrainz Server. See the release notes for update instructions.

P.S. Search upgrades occurred separately ten days later.

MusicBrainz schema change release, 2024-05-13 (with upgrade instructions)

We’re happy to announce the release of our May 2024 schema change now! Thanks to all who were patient during yesterday’s downtime as we released everything to our production servers. Final testing for the mirrors also took some more time. Note that the initially announced upgrades for MusicBrainz search engine are just about to reach our beta website, and thus are postponed for mirrors too but can be expected for the few next releases.

This is a fairly small schema change release which mostly removes unused code and improves things behind the scenes. Of the schema change tickets, there are only two that will directly affect users as they browse and edit in MusicBrainz. The first (MBS-13421) adds genre collections, so that editors can for example make a list of their favorite genres. The second (MBS-13514) allows entering 6-digit label codes.

Additionally, derat gratified us with making aliases more visible in the website, and some other improvements, while yellowhatpro polished cover art priority.

Thanks to chaban, cyberskull, thomasegger, Toad King, and wileyfoxyx for having reported bugs and suggested improvements. Thanks to 0x1026, Anonymous, “ApeKattQuest, MonkeyPython”, AshPigeon, Autom, brtc, chaban, claybiockiller, danBLOO, darlingz, eigenric, Evergarden, GABG, hashflu, hesheng, julian45, kellnerd, LiarOnce, Philipp Wolfer, salo.rock, suming, Vac31., wileyfoxyx, x1ao4, xiaole_0714223, yangmouren, yyb987, and zemeles for updating the translations. And thanks to all others who tested the beta version!

A new release of MusicBrainz Docker is also available that matches this update of MusicBrainz Server. See the release notes for update instructions.

MusicBrainz schema change release, 2023-05-15 (with upgrade instructions)

We’re happy to announce the release of our May 2023 schema change today! Thanks to all who were patient during today’s downtime as we released everything to our production servers, and thanks to CatQuest, jesus2099, and yindesu for creating tickets.

The first (MBS-12800) makes it so that cancelled releases are ignored when calculating the first release dates for recordings and release groups; since something that was cancelled was by definition not released, it should not be used as a first release date.

The second (MBS-11312) lays the foundation for a new feature (MBS-4685) that will allow users to edit or delete their edit notes, as long as a set of conditions are met (see the edit note docs for details). Admins will be able to edit or delete any edit notes at any time (MBS-13084), mostly to get rid of spam or offensive content, but also to help any editor who cannot change their note anymore but has an important reason why they need to do so. This feature will be available for testing in our beta server on Tuesday and we expect to release it next week, assuming our beta testers don’t find any too big issue with it by then.

A new release of MusicBrainz Docker is also available that matches this update of MusicBrainz Server. See the release notes for update instructions.

MusicBrainz schema change release, 2022-05-16 (with upgrade instructions)

We’re happy to announce the release of our May 2022 schema change today! Thanks to all who were patient during today’s downtime as we released everything to our production servers, and thanks to ikerm2003, mfmeulenbelt rinmon and salo.rock for updating the translations.

This is once again a fairly minor release as far as schema changes go, but please do report any issues that you come across, especially related to the propagation of ratings and tags.

MusicBrainz schema change release, 2021-05-17 (with upgrade instructions)

We’re happy to announce the release of our May 2021 schema change today! Thanks to all who were patient during today’s downtime as we released everything to our production servers.

This is a fairly minor release as far as schema changes go, but please do report any issues that you come across, especially related to the display of recordings, releases and release groups on artist and release group pages.

New, user-facing changes with this release are limited to the new ability to merge collections (MBS-10208) and the addition of ratings for places (MBS-11451). Additionally, MBS-11463 adds a new view that is used to fix a couple small requests related to disc IDs (MBS-11268) and release length calculation (MBS-11349). Two other changes – adding a first-release-date field to recordings (MBS-1424) and support for PKCE in OAuth (MBS-11097) are more or less end-user affecting but were already released on the main MusicBrainz servers a while ago. All other changes are under the hood only.

We ran into a few complications while working on this schema change update, so we decided to postpone two changes to our October schema change to ensure only stuff we are more confident on is released. Those are MBS-11457, which involves dropping the ordering_attribute column for series and would have had no direct effect on user experience, and MBS-11456, which would have added MBIDs for artist credits.

A few of the released new features and improvements — namely the first-release-date field for recordings, and the performance improvements to artist pages — make use of new materialized tables. These tables aren’t dumped, nor are they replicated, since they’re derived entirely from primary table data. Rather, we’ve added a new script to build them (admin/BuildMaterializedTables, included in the upgrade instructions below), and triggers to keep them up-to-date once they’re built. These triggers are created on replicated servers, too. If you use the web interface or web service at all, just note the extra step of running BuildMaterializedTables after upgrade.sh below!

A new release of MusicBrainz Docker is also available that solves an issue for live indexing and matches this update of MusicBrainz Server. See the release notes for update instructions.

Now, on to the instructions.

Schema Change Upgrade Instructions

Note: Importing the latest data dump is always a valid alternative to running ./upgrade.sh on an existing database, if you’d prefer to also get new data in one go. Just follow the relevant instructions in INSTALL.md. The git tag is v-2021-05-19-hotfixes. The rest of the instructions here assume an in-place upgrade.

Make sure DB_SCHEMA_SEQUENCE is set to 25 in lib/DBDefs.pm.
If you’re using the live data feed (your REPLICATION_TYPE is set to RT_SLAVE), ensure you’ve replicated up to the most recent replication packet available with the old schema. If you’re not sure, run ./admin/replication/LoadReplicationChanges and see what it tells you; if you’re ready to upgrade, it should say “This replication packet matches schema sequence #26, but the database is currently at #25.”
Take down the web server running MusicBrainz, if you’re running a web server.
Turn off cron jobs if you’re automatically updating the database via cron jobs.
If you’re using the live search indexing, stop it and, assuming sir is under the same directory as musicbrainz-server, run cd ../sir && python2.7 -m sir triggers && cd - && ./admin/psql < ../sir/sql/DropTriggers.sql && ./admin/psql < ../sir/sql/DropFunctions.sql
Switch to the new code with git fetch origin followed by git checkout v-2021-05-19-hotfixes.
Install newer dependencies Perl 5.30 or later and NodeJS 16 according to install prerequisites.
Run cpanm --installdeps --notest . (note the dot at the end) to ensure your perl-based dependencies are up to date.
Run ./upgrade.sh (it may take a while to vacuum at the end).
Set DB_SCHEMA_SEQUENCE to 26 in lib/DBDefs.pm as instructed by the output of ./upgrade.sh.
If you’re using the web interface or web service, run ./admin/BuildMaterializedTables --database=MAINTENANCE all to build new materialized tables. These will take several additional gigabytes of spaces and be kept up-to-date automatically via triggers. For more information, see INSTALL.md.
If you’re using the live search indexing, assuming sir is under the same directory as musicbrainz-server, run cd ../sir && git fetch origin && git checkout v2.1.0 && python2.7 -m sir triggers && cd - && ./admin/psql < ../sir/sql/CreateFunctions.sql && ./admin/psql < ../sir/sql/CreateTriggers.sql and rebuild indexes (by running cd ../sir && python2.7 -m sir reindex && cd -) then start it in watch mode (with cd ../sir && git fetch origin && git checkout v2.1.0 && python2.7 -m sir amqp_watch)
Turn cron jobs back on, if applicable.
Restart the MusicBrainz web server, if applicable. It’s also recommended you restart Redis. If you’re accessing your MusicBrainz server in a web browser, run ./script/compile_resources.sh.

Here’s the list of resolved tickets:

New Feature

[MBS-10208] – Allow merging collections
[MBS-11451] – Support ratings for places
[MBS-11463] – Add view to easily access medium track lengths
[MBS-11652] – Add support for artist series (hotfixed)

Improvement

[MBS-10962] – Speed up listing artist’s releases
[MBS-11268] – Show “Set track durations” on release/discids page
[MBS-11460] – Add materialized tables to fetch release groups by artist or track artist

Database Schema Change Task

[MBS-10647] – Add [no label] to b_del_label_special trigger for labels
[MBS-11453] – Change entity0_cardinality, entity1_cardinality to SMALLINT
[MBS-11459] – Create the edit_data_type_info function on mirrors
[MBS-11464] – Drop table statistics.log_statistic
[MBS-11466] – Change language.frequency and script.frequency to SMALLINT

Previously Released Changes

[MBS-1424] – Add a ‘First release date’ field to recordings
[MBS-10821] – Edit changing medium tracklist and format is stuck
[MBS-11097] – Support PKCE (Proof Key for Code Exchange) by OAuth clients
[MBS-11431] – Speed up /ws/js/check_duplicates

PostgreSQL 12 Upgrade Instructions for MusicBrainz Server

Thanks to everyone for your patience during our downtime today. As promised, here are steps to follow to upgrade your own PG instance to v12. (Confused? See the previous blog post on this subject.)

If you’re already running v12, there are still some instructions you must follow!

For MusicBrainz Docker

If you’re running the new MusicBrainz Docker setup, an upgrade script exists for you to use. See the release notes for specific – hopefully brief – instructions.

For a Manual Setup (INSTALL.md Based)

If you aren’t using Docker but rather set up musicbrainz-server by hand following INSTALL.md, see the steps below.

Know that as an alternative, you can always import new data dumps from scratch (again following the steps in INSTALL.md) into a new PG 12 cluster. Just make sure you’re on the v-2020-05-18-postgres12 tag of musicbrainz-server while doing so.

If on the other hand you don’t mind getting your hands a bit dirty, you can use the quicker method below. Like INSTALL.md, this assumes you’re using Ubuntu/Debian and their postgresql-common cluster management tools.

If you’re already running v12, you should still follow these steps; however, you can skip the ones involving apt-get, pg_dropcluster, and pg_upgradecluster. The main steps you need to follow in this case are running the 20200518-pg12-before-upgrade.sql and 20200518-pg12-after-upgrade.sql scripts in that order.

On distros other than Debian/Ubuntu where the postgresql-common tools aren’t available, you’ll have to manage with initdb and pg_upgrade on your own.

First take down the web server running MusicBrainz (stop plackup) to prevent database access.
Turn off any cron jobs updating or accessing the database (e.g. for the live data feed/replication packets).

Switch to the latest musicbrainz-server code with:

git fetch origin && \
    git checkout v-2020-05-18-postgres12

With PG 9.5 (or whatever version you’re using) still running, run the following “pre-upgrade” script:
```
psql -U postgres -d musicbrainz_db \
     -f admin/sql/updates/20200518-pg12-before-upgrade.sql 
```
This assumes that “postgres” is the name of your PG superuser, and “musicbrainz_db” is the name of your database. If you see a few messages about things not existing, that’s normal.
Install packages for PostgreSQL 12. On Ubuntu/Debian you can obtain them from the PGDG apt repo.
```
apt-get update && \
    apt-get install postgresql-12 postgresql-server-dev-12 
```
If you’re installing postgresql-12 for the first time, this will automatically create a new cluster at /var/lib/postgresql/12/main. Remove that empty cluster. Don’t run this if you already had v12 installed and have data there!
```
pg_dropcluster --stop 12 main
```
If you did already have v12 installed with musicbrainz_db running there, leave the cluster alone and skip the next step involving pg_upgradecluster.

In the unlikely event that you already have a v12 cluster, but also have musicbrainz_db running in a separate, older cluster, these instructions won’t work for you. We recommend importing fresh data dumps into the v12 cluster and dropping the old one.
Upgrade the old cluster. This assumes it’s version 9.5; if you’re using version 10 or 11, make sure to replace 9.5 below with 10 or 11. If you have other databases in your old cluster besides musicbrainz_db, be aware that this will upgrade all of them to PG 12.
```
 pg_upgradecluster -v 12 9.5 main
```
If all goes well, the new cluster should be up and running. (You can drop the old one if you like; the output of the pg_upgradecluster command will tell you how.) Now run the following “post-upgrade” script on the database:
```
psql -U postgres -d musicbrainz_db -f \
     admin/sql/updates/20200518-pg12-after-upgrade.sql
```
This may take a bit, as it has to recreate some indexes.
The upgrade is complete. You can turn cron jobs back on, if applicable.
Restart the MusicBrainz web server / plackup, if applicable. If you’re accessing the server in a web browser, the usual release upgrade steps apply, like running ./script/compile_resources.sh again.

If you run into any trouble following the above, please let us know and we’ll try to help resolve your issue as soon as possible!

MusicBrainz schema change release, 2019-05-13 (with upgrade instructions)

We’re happy to announce the release of our May 2019 schema change today! Thanks to all who were patient during today’s downtime as we released everything to our production servers.

This is a fairly minor release as far as schema changes go, but please do report any issues that you come across, especially any related to genres and collections.

Visible changes with this release are limited to an indication if a specific artist credit is being edited (MBS-5387). Work on some of the changes to collections and genres is quite advanced, and we’re hoping to release some of the new features onto beta already in a week or so from now, while others might take a while longer.

Now, on to the instructions.

Schema Change Upgrade Instructions

Note: Importing the latest data dump is always a valid alternative to running ./upgrade.sh on an existing database, if you’d prefer to also get new data in one go. Just follow the relevant instructions in INSTALL.md. The git tag is v-2019-05-13-schema-change. The rest of the instructions here assume an in-place upgrade.

Make sure DB_SCHEMA_SEQUENCE is set to 24 in lib/DBDefs.pm.
If you’re using the live data feed (your REPLICATION_TYPE is set to RT_SLAVE), ensure you’ve replicated up to the most recent replication packet available with the old schema. If you’re not sure, run ./admin/replication/LoadReplicationChanges and see what it tells you; if you’re ready to upgrade, it should say “This replication packet matches schema sequence #25, but the database is currently at #24.”
Take down the web server running MusicBrainz, if you’re running a web server.
Turn off cron jobs if you’re automatically updating the database via cron jobs.
Switch to the new code with git fetch origin followed by git checkout v-2019-05-13-schema-change.
Install newer dependencies Yarn and NodeJS 8 or later according to install prerequisites.
Run cpanm --installdeps --notest . (note the dot at the end) to ensure your perl-based dependencies are up to date.
Run ./upgrade.sh (it may take a while to vacuum at the end).
Set DB_SCHEMA_SEQUENCE to 25 in lib/DBDefs.pm as instructed by the output of ./upgrade.sh.
Turn cron jobs back on, if applicable.
Restart the MusicBrainz web server, if applicable. It’s also recommended you restart redis. If you’re accessing your MusicBrainz server in a web browser, run ./script/compile_resources.sh.

Here’s the list of resolved tickets:

Bug

[MBS-5387] – ACs being edited aren’t marked as having pending edits on the aliases tab
[MBS-9365] – event_meta_fk_id was never created as part of any upgrade script
[MBS-9462] – Standalone databases created before schema 21 are missing some l_event_url triggers
[MBS-10146] – Regression: ISE on Remove DiscID page
[MBS-10149] – Swap track titles with artist credits fails to update both fields properly
[MBS-10150] – Regression: The link to the release group reviews in the release page is broken

Improvement

[MBS-9664] – Add database constraints to disallow loop relationship
[MBS-10044] – Add place area to place lists

Database Schema Change Task

[MBS-10052] – Add new schema for the event art archive
[MBS-10173] – Create a genre table in the DB and populate it with existing genres
[MBS-10174] – Create an addition timestamp in the DB for new collection items
[MBS-10175] – Create a position integer in the DB for collection items
[MBS-10176] – Create a comment text field in the DB for collection items
[MBS-10177] – Create an editor_collection_collaborator table for collaborative collections
[MBS-10178] – Create a genre_alias table
[MBS-10181] – Create filesize for cover art and each thumb in the DB

React Conversion Task

[MBS-9925] – Convert collection pages to React
[MBS-10179] – Convert all entity list components to React

Schema change release, 2017-05-15 (including upgrade instructions)

We’re happy to announce the release of our May 2017 schema change today! Thanks to all who were patient during today’s downtime as we released everything to our production servers.

This is a fairly minor release as far as schema changes go, but please do report any issues that you come across.

Currently, the only visible change for editors is the ability to add multiple lyrics languages to works. We’ve also modified the schema to support dynamic attributes for entities other than works, but the UI for that won’t be complete for another release or two.

Now, on to the instructions.

Schema Change Upgrade Instructions

Note: Importing the latest data dump is always a valid alternative to running ./upgrade.sh on an existing database, if you’d prefer to also get new data in one go. Just follow the relevant instructions in INSTALL.md. The rest of the instructions here assume an in-place upgrade.

Make sure DB_SCHEMA_SEQUENCE is set to 23 in lib/DBDefs.pm.
If you’re using the live data feed (your REPLICATION_TYPE is set to RT_SLAVE), ensure you’ve replicated up to the most recent replication packet available with the old schema. If you’re not sure, run ./admin/replication/LoadReplicationChanges and see what it tells you; if you’re ready to upgrade, it should say “This replication packet matches schema sequence #24, but the database is currently at #23.”
Take down the web server running MusicBrainz, if you’re running a web server.
Turn off cron jobs if you’re automatically updating the database via cron jobs.
Switch to the new code with git fetch origin followed by git checkout v-2017-05-15-schema-change.
Run cpanm --installdeps --notest . (note the dot at the end) to ensure your perl-based dependencies are up to date.
Downgrade DBD::Pg by running cpanm TURNSTEP/DBD-Pg-3.5.3.tar.gz (version 3.6.0 breaks things currently).
Run ./upgrade.sh (it may take a while to vacuum at the end).
Set DB_SCHEMA_SEQUENCE to 24 in lib/DBDefs.pm as instructed by the output of ./upgrade.sh.
Turn cron jobs back on, if applicable.
Restart the MusicBrainz web server, if applicable. It’s also recommended you restart redis. If you’re accessing your MusicBrainz server in a web browser, run npm install followed by ./script/compile_resources.sh.

For those curious, here’s the list of resolved tickets (excluding MBS-8393):

Bug

[MBS-9329] – event_meta is empty

New Feature

[MBS-9271] – Prevent usernames from being reused

Task

[MBS-9273] – Fix the a_ins_edit_note function in older setups to not populate edit_note_recipient for own notes
[MBS-9274] – Fix the edit_note_idx_post_time_edit index in older setups to handle NULL post_time

Improvement

[MBS-5452] – Support multiple lyric language values for works

Schema change release, 2016-05-23 (with upgrade instructions)

Starting with this release, PostgreSQL 9.5 is now our minimum supported version. In order to import any future data sets, you will need to upgrade your installation to version 9.5.

Due to unforeseen problems with the Live Data Feed (AKA replication), users with slave databases will be required to first import a fresh data dump into their new 9.5 installation. We apologize that this is the case, but even had this stream not been broken, doing a clean import is faster and easier than doing the migration. For details on what happened during this rather lengthy schema change release, stay tuned for a post mortem blog post that covers the details.

If you have a non-replicated standalone database, you can use pg_upgrade and run ./upgrade.sh directly, but for simplicity we strongly recommend importing the latest data dump. Thus, we will only provide instructions for a clean import:

Make sure you have PostgreSQL 9.5 installed, and your database settings in lib/DBDefs.pm are updated to point to the 9.5 installation if you currently have an older version of postgres running. If you already have postgres 9.5 and want to replace the existing database there, you’ll need to drop it first (using dropdb or from within psql). Be careful that you’re not dropping any important data if this is a standalone database that you’ve made changes to.
Take down the web server running MusicBrainz, if you’re running a web server.
Turn off cron jobs if you are automatically updating the database via cron jobs.
Switch to the new code with git fetch origin followed by git checkout v-2016-05-23-schema-change-v2
Run cpanm --installdeps --notest . to ensure your perl-based dependencies are up to date. Note the dot at the end.
Set DB_SCHEMA_SEQUENCE to 23 in lib/DBDefs.pm
Download the latest data dumps. If you don’t need historical edit data, excluding the edit dump will speed up your import significantly.
Initialize a new database from the data dumps downloaded in step 7. Detailed instructions for doing this are located in INSTALL.md in the musicbrainz-server repository; if your data dumps are in /tmp, the command should simply be something like ./admin/InitDb.pl --createdb --import /tmp/mbdump*.tar.bz2.
After the import has finished, turn cron jobs back on, if applicable.
Restart the MusicBrainz web server, as well as memcached, if applicable.

We would like to thank bitmap, Gentlecat, zas, chirlu, reosarevok, gcilou for contributing directly to the release and we’d also like to thank all of the people who helped test, debug or otherwise offer support in this quite difficult release. Thank you!

And finally, here’s the list of changes you can expect in the upgrade:

Bug

[MBS-6406] – Admins can’t change email addresses
[MBS-8288] – Missing indexes for inverse lookup on *_gid_redirect tables
[MBS-8669] – Primary key for place table missing on old slaves
[MBS-8906] – Release pages ISE if CB doesn’t return JSON from its API for whatever reason
[MBS-8928] – If you submit the release editor without being logged in, it displays “[object Object]” as an error mesage
[MBS-8943] – Some pages do not respect DB_READ_ONLY setting

Improvement

[MBS-1873] – Fix vote tallies for edits
[MBS-3887] – Duplicate artist and label names not being checked against alias
[MBS-8287] – Log deleted entities that were in a subscribed collection
[MBS-8433] – Work attributes don’t have a uuid
[MBS-8716] – Store the edit data in a JSONB column
[MBS-8717] – Move the edit data to a separate table
[MBS-8838] – Add gids to all *_type* tables
[MBS-8873] – Convert and unify artist credit editors to React
[MBS-8909] – Add logos to IMDb and VGMdb links in the sidebar
[MBS-8939] – Update the Instagram logo used in the sidebar
[MBS-8940] – Let banner message editors dismiss the banner only temporarily

Task

[MBS-8656] – Bring edit table indexes back into sync
[MBS-8719] – Stop materializing of edit and vote counts
[MBS-8720] – Add a materialized view of edit note recipients
[MBS-8727] – Prevent duplicate votes
[MBS-8800] – Create the earthdistance extension and add a geodetic index for place coordinates
[MBS-8804] – Add BRIN indexes for timestamp columns
[MBS-8897] – add new entity icons
[MBS-8938] – Schema changes to support alternative tracklists