bmmbmm01/plex-dbrepair repository overview

⁠YOU ARE RESPONSIBLE FOR YOUR OWN DATA.

⚠️ This container modifies your Plex SQLite database.
Always ensure you have verified, working backups before proceeding.

⁠Plex DBRepair Docker

One-shot Plex database maintenance for Docker and Unraid Community Applications.

Docker Hub⁠ · GitHub source⁠ · Unraid CA template⁠ · Support thread⁠

This image bundles ChuckPa DBRepair v26.10.00, the compiled upstream utility. It does not run the legacy DBRepair.sh or the old custom SQLite/FTS code.

⁠What it does

1. Connects to the host Docker daemon using /var/run/docker.sock (no nested Docker daemon).
2. Locates exactly one running Plex container by its name/image and verifies the expected Plex database exists, or uses the exact container selected by PLEX_CONTAINER_NAME.
3. Logs the Plex container name, image, ID, relevant mounts, restart policy, and database path.
4. Copies ChuckPa's bundled DBRepair executable into the target Plex container under /tmp/plex-dbrepair-runner and executes it with docker exec.
5. Requests a graceful Plex Media Server shutdown using DBRepair stop; if necessary and permitted, sends SIGTERM to the Plex server process. The Plex container must remain running for maintenance through docker exec.
6. Creates a timestamped cold database backup before maintenance when ENABLE_BACKUPS=true (except prune), executes the requested operation, and by default restarts the Plex Docker container after a successful run.
7. Writes output to Docker logs and a persistent timestamped log, then exits.

No Plex appdata bind mount is required on the repair container. PLEX_MOUNT=/config refers to the internal path within the target Plex container, not a volume mapping for DBRepair.

This implementation has no offline repair fallback if the target Plex container exits or the Plex process cannot remain stopped.

⁠Install using Unraid Community Applications

Install using the Unraid plexrepair.xml template⁠.

For most users, the defaults are sufficient:

• DBREPAIR_MODE=automatic
• PLEX_CONTAINER_NAME=auto
• ENABLE_BACKUPS=true
• RESTART_PLEX=true
• Docker socket mounted at /var/run/docker.sock
• A persistent host directory mounted at /logs

Set the DBRepair container restart policy to No. It is a one-shot maintenance job, not a continuously running service. Do not configure always or unless-stopped for the repair container.

The Plex server container must be running initially. DBRepair then stops its internal PMS process for maintenance. If several Plex installations are found, set PLEX_CONTAINER_NAME to the exact name shown by docker ps (for example plex).

Normally Plex's internal library root is /config/Library/Application Support/Plex Media Server. Advanced users with custom internal paths may change PLEX_MOUNT and PLEX_REL.

Security: Access to the Docker socket grants effective administrative control over the host. Install only images and scripts you trust. Docker's --privileged option is not required.

⁠Docker CLI example

docker run --name plex-dbrepair-test \
  --hostname plex-dbrepair-test \
  --network bridge \
  --restart no \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /mnt/user/appdata/plex-dbrepair-logs:/logs \
  -e DBREPAIR_MODE=automatic \
  -e PLEX_CONTAINER_NAME=auto \
  -e PLEX_CONTAINER_MATCH=plex \
  -e PLEX_MOUNT=/config \
  -e PLEX_REL='Library/Application Support/Plex Media Server' \
  -e ENABLE_BACKUPS=true \
  -e ALLOW_PLEX_KILL=true \
  -e RESTART_PLEX=true \
  -e PRUNE_DAYS=30 \
  -e DBREPAIR_TIMEOUT=7200 \
  -e STOP_TIMEOUT=90 \
  bmmbmm01/plex-dbrepair:latest

The /mnt/user/appdata/... path above is an Unraid example; replace it with an appropriate host directory on other systems, such as /VMs/docker/plex-dbrepair-logs on a PVE/Debian host.

To repeat a run, first remove the stopped repair container, not the Plex container:

docker rm plex-dbrepair-test

Useful commands after a run (before removing the repair container):

docker logs plex-dbrepair-test
docker inspect plex-dbrepair-test --format '{{.State.ExitCode}}'
docker ps --filter name=plex

Check that the Plex application is responding after the repair; an exit code of 0 alone does not prove all media services are healthy.

⁠Maintenance modes

Unknown mode strings fall back to automatic. Errors in detection, shutdown, backup, or maintenance do not trigger an automatic repair fallback. Legacy ftscheck maps to check and ftsrepair maps to reindex. manual is rejected by this one-shot entrypoint.

⁠Environment variables

Legacy ENABLE_FTS_CHECK and ENABLE_FTS_REPAIR variables are no longer needed; the compiled upstream DBRepair utility manages compatible FTS operations itself.

⁠Backups, failures, and recovery

When enabled, archives are created inside the target Plex configuration, not inside the repair container:

/config/Library/Application Support/Plex Media Server/DBRepair-Backups/dbrepair-pre-auto-YYYYMMDDTHHMMSSZ.tar.gz

Backups contain the Plug-in Support/Databases directory, including any present SQLite WAL/SHM files. The script creates the archive while Plex Media Server is stopped and checks that the archive can be listed. This is not the same as testing a full restore.

Backups are not automatically pruned; large Plex libraries need sufficient free space. Maintain your own independent backup strategy. The older RESTORE_LAST_BACKUP feature is not implemented in this rewrite; recovery requires deliberate backup selection and manual restore procedures.

If PMS restarts unexpectedly, its container exits, or DBRepair encounters a failure or timeout, the tool may exit without bringing Plex back online. In particular, a failure during active database maintenance intentionally avoids automatic restart. Inspect the persistent logs and database state before restarting Plex manually.

⁠Important: Plex /tmp compatibility

The current image stages its DBRepair executable at /tmp/plex-dbrepair-runner inside the Plex container. That directory must be writable, accessible via docker cp, and executable.

Custom Docker Compose tmpfs mappings of /tmp can cause problems, especially if the filesystem has the noexec mount option. Observed errors include:

Error: No such container:path: ...:/tmp/plex-dbrepair-runner
ERROR: Cannot copy DBRepair to Plex
permission denied

Check the target Plex mount options:

docker exec plex sh -c "grep ' /tmp ' /proc/mounts"

For example, this Compose configuration may be incompatible:

tmpfs:
  - /tmp:size=1g,mode=1777

If you experience executable staging failures, the simplest supported approach is to disable the custom /tmp tmpfs mapping and recreate the Plex container, then rerun the repair. Removing a tmpfs mapping does not guarantee success if the replacement /tmp is also noexec or otherwise restricted. The current published image does not automatically fall back to /config.

An executable staging failure happens before database maintenance. Read the DBRepair container logs to confirm where it stopped.

⁠Test history and compatibility

LinuxServer Plex, disposable test library (PMS 1.43.4.10903, DBRepair 26.10.00):

PVE production LinuxServer Plex: Automatic mode completed integrity and orphan checks, created a cold backup, and reported a successful Docker restart and exit 0 after staging the executable in an alternate executable directory as a manual test workaround. The unmodified public image initially failed on that host because Plex's /tmp was tmpfs-mounted with noexec. This workaround is not included in the published image.

These tests do not establish successful recovery from an actually corrupted database, meaningful deflate compaction, deletion of real aged cache files, or compatibility with every Plex container or future Plex database schema. Binhex and Hotio remain unverified. Check upstream DBRepair releases⁠ for compatibility information.

⁠Licensing and upstream credits

DBRepair is developed by ChuckPa and remains proprietary software. Copyright © 2022–2026 ChuckPa. All rights reserved. The compiled DBRepair program is distributed under its own license, which requires express written permission for redistribution. A separate license on this Docker wrapper does not change the terms of the upstream executable.

• ChuckPa DBRepair project⁠
• Upstream DBRepair license⁠
• Official DBRepair releases⁠

The Dockerfile, entrypoint automation, documentation, and Unraid integration are independently maintained by bmartino1. Review this repository's LICENSE and any third-party notices for the wrapper's applicable terms. This is an independent community integration; it is not an official Plex or ChuckPa release.

Redistributors: Verify that your distribution of the bundled DBRepair executable is expressly authorized by ChuckPa. A link or attribution alone does not grant redistribution permission.

⁠Support

• Unraid support forum⁠
• Docker Hub⁠
• Wrapper source and issues⁠
• Upstream DBRepair⁠