Jellyfin SQLite Database Repair Guide

This document explains how to use the fix_jellyfin_db.sh script to repair a corrupted Jellyfin library.db file.

Warning: Repeated database corruption is a strong indicator of an underlying issue, most commonly a failing hard drive or SSD. If you have to run this script more than once, you should immediately investigate the health of your storage device using tools like smartctl.

How to Use the Script

Save the Script: Save the script content to a file named fix_jellyfin_db.sh on your server.
Make it Executable: Open a terminal and navigate to the directory where you saved the file. Run the following command to make it executable:
```
chmod +x fix_jellyfin_db.sh
```
Run the Script: The script must be run with sudo because it needs to stop/start system services and modify files in /var/lib/jellyfin/.
```
sudo ./fix_jellyfin_db.sh
```

The script will print its progress as it executes each step.

What the Script Does: A Step-by-Step Breakdown

The script automates the standard "dump and restore" method for SQLite recovery.

Step 1: Stops the Jellyfin Service

To prevent any other process from reading or writing to the database during the repair, the script first stops Jellyfin.

systemctl stop jellyfin

Step 2: Backs Up the Corrupted Database

Your corrupted database is never deleted. It is copied to a new file with a timestamp, ensuring you have a fallback.

# Example backup name: library.db.corrupt.2023-10-27-14:30:00
cp library.db library.db.corrupt.[timestamp]

Step 3: Dumps Data to an SQL File

It uses the sqlite3 command-line tool to read every piece of data it can from the corrupted database and write it as a series of SQL commands to a text file named library_dump.sql.

sqlite3 library.db .dump > library_dump.sql

Step 4: Patches the Dump File

If the dump process hit a severe error, it writes ROLLBACK; at the end of the dump file. This would cause the import to fail. The script checks for this exact line and replaces it with COMMIT;, forcing SQLite to save all the data it was able to salvage.

sed -i '$ s/ROLLBACK; -- due to errors/COMMIT;/' library_dump.sql

Step 5: Restores the Database

The script renames the original corrupted file and then creates a brand new, empty library.db by feeding it the library_dump.sql file. This rebuilds the entire database structure from scratch, leaving all corruption behind.

# Move old DB
mv library.db library.db.repaired-from

# Create new DB from dump
sqlite3 library.db < library_dump.sql

Step 6: Verifies the New Database

The script checks that the new database file is not empty. It then runs PRAGMA integrity_check, which should return ok on a healthy database.

sqlite3 library.db "PRAGMA integrity_check;"

Step 7: Sets Permissions and Restarts Jellyfin

Finally, it sets the correct jellyfin:jellyfin ownership and file permissions on the new database file and restarts the Jellyfin service.

chown jellyfin:jellyfin library.db
chmod 664 library.db
systemctl start jellyfin

Post-Repair Actions

After the script completes successfully, you should verify that your Jellyfin library, users, and watch history are intact.

The script leaves the backup files in /var/lib/jellyfin/data/ for safety:

library.db.corrupt.[timestamp]
library.db.repaired-from
library_dump.sql

Once you have confirmed Jellyfin is working correctly for a day or two, you can safely delete these files to save space:

sudo rm /var/lib/jellyfin/data/library.db.corrupt.* /var/lib/jellyfin/data/library.db.repaired-from /var/lib/jellyfin/data/library_dump.sql

3.7 KiB Raw Blame History