# 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

1.  **Save the Script:**
    Save the script content to a file named `fix-jellyfin-db.sh` on your server.

2.  **Make it Executable:**
    Open a terminal and navigate to the directory where you saved the file. Run the following command to make it executable:
    ```bash
    chmod +x fix-jellyfin-db.sh
    ```

3.  **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/`.
    ```bash
    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.
```bash
systemctl stop jellyfin
```
q
#### 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.
```bash
# 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`.
```bash
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.
```bash
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.
```bash
# 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.
```bash
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.
```bash
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:
```bash
sudo rm /var/lib/jellyfin/data/library.db.corrupt.* /var/lib/jellyfin/data/library.db.repaired-from /var/lib/jellyfin/data/library_dump.sql
```