Skip to main content

Database Upgrades

briiian
Authored by briiian · Last updated
self-hosted

Some releases of Cardinal Media Server change the shape of the database. The server applies those changes, called migrations, by itself when it starts. You don't have to do anything, but it helps to know what happens so that you can recover if an upgrade goes wrong.

What happens when the server starts​

  1. The server compares your database to the version you are running and finds the migrations it hasn't applied yet.
  2. On SQLite, it saves a copy of the database before changing anything (see Backups).
  3. It applies the migrations one at a time. Each one is all-or-nothing: if a migration fails, the database is left exactly as it was before that migration.
  4. If a migration fails, the server stops instead of starting on a half-upgraded database, and the logs show the help code ERR_CHS_0019.

The first time you start a version that uses migrations, the server converts your existing database once. The logs say This database predates migrations and then The database is now managed by migrations. Your libraries, users, and settings are kept.

SQLite backups​

Before it changes a SQLite database, the server copies it to a migration-backups folder next to the database file. In the Docker image that is:

/config/db/migration-backups/

Each backup is named after the upgrade that came next, for example cardinal-media-server.sqlite3.db.before-migrations. The server keeps the 3 most recent backups and deletes older ones. Each one is a full copy of your database, so make sure the disk has room for at least one more copy.

PostgreSQL​

Migrations on PostgreSQL run in transactions, so a failed migration is rolled back. The server doesn't back up PostgreSQL databases. Take a snapshot with your usual tools (for example pg_dump) before you upgrade to a new release.

If an upgrade fails (ERR_CHS_0019)​

The log line before the help code says which migration failed and why. On SQLite, it also gives the path of the backup that was made before the upgrade.

To go back to the version you were running before:

  1. Stop the server.
  2. SQLite: replace the database file with the backup. For example, in the Docker image, copy /config/db/migration-backups/cardinal-media-server.sqlite3.db.before-<name> to /config/db/cardinal-media-server.sqlite3.db. If you use WAL mode, also delete the -wal and -shm files next to the database.
  3. PostgreSQL: restore the snapshot that you took before the upgrade.
  4. Start the version you were running before.

Then let us know which version you were upgrading from and to, along with the log lines from the failed start.

warning

Don't start an older version of the server against a database that a newer version has already upgraded. Older versions don't know about the newer changes. Restore a backup instead.

Was this article helpful?