jellyfin restoration info and shell scripts

jellyfin/restore_corrupted_database.md

@@ -0,0 +1,91 @@
+# 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
+```
+
+#### 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
+```