[Feature Request]: Integrity check failed during MySQL restore & Request for backup verification feature

[edmc73]

Problem / Motivation

When attempting to restore a MySQL database from the latest backup using dbackup, the process fails due to an integrity check error. Interestingly, the second-to-last backup restores perfectly fine without any issues.

dbackup-1  | {"level":"error","message":"Restore service error","timestamp":"2026-05-23T11:06:48.556Z","context":{"service":"RestoreService"},"error":{"name":"t","message":"Backup file integrity check failed. The file may be corrupted or tampered with.","stack":"t: Backup file integrity check failed. The file may be corrupted or tampered with.\n    at /app/.next/server/chunks/[root-of-the-server]__03k~~2m._.js:1:10330\n    at L (/app/.next/server/chunks/0ddr_next_dist_esm_build_templates_app-route_0el4550.js:1:12012)\n    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)","code":"UNKNOWN_ERROR"}}

Proposed Solution

To prevent discovering corrupted backups only during a critical restore process, would it be possible to add an integrity check feature?

Ideally, this could include:

A button in the UI to manually verify a backup's integrity.

An automated background task (or cron job) that verifies the checksum immediately after a backup is created.

Alternatives Considered

No response

Area

Backup / Restore

Additional Context

No response

[edmc73]

Here is a checksum test on my recent backups, comparing the calculated SHA-256 with the checksum value stored in the .meta.json file:

There are quite a few mismatches, but I strongly doubt that all these backup files are actually corrupted.

Could this be a bug in how the checksum is computed or saved during the backup creation phase? (e.g., hashing the uncompressed SQL file instead of the final .gz archive, or a race condition before the file is fully written to disk?)

[edmc73]

Please disregard my previous comment regarding a potential bug in the checksum calculation. The issue actually seems to stem from my NAS, as the secondary storage where the backups are replicated has absolutely no integrity issues (all checksums match perfectly there).

That being said, I still believe that a built-in backup integrity verification feature would be an essential and highly valuable addition to the application.

[Skyfay]

Hey @edmc73

There is actually already a task for this.

But its disabled by default because it needs to download every backup to check integrity.

This just isn't possible, especially with larger backups or a large number of them. If you have any ideas on how to improve this, I'd love to hear your feedback.

[edmc73]

Sorry, I used an AI assistant to help me structure and write down these technical optimization ideas clearly in English.

To make the integrity check efficient across all supported storage types, we can adapt the strategy depending on the connection protocol. This completely avoids downloading full files in almost every scenario:

1. Local Filesystem & Direct Mounts (SMB, WebDAV, Local)

Local / SMB / WebDAV: Since these are mounted or directly accessible by the application container, the checksum can be computed instantly on the local path. No network download is needed.

2. Remote Terminal Storages (SSH, SFTP, Rsync)

SSH / SFTP / Rsync: Instead of pulling the file back, the application can execute a remote command through the existing connection to let the destination server do the heavy lifting:

sha256sum /path/to/backup.sql.gz
The app only receives the final 64-character hash string back, reducing network overhead to a few bytes.

3. Object Storages (S3, Cloudflare R2, Hetzner Object Storage)

• S3-Compatible APIs: Cloud providers automatically calculate and store checksums upon upload (like the ETag for MD5, or native SHA-256 headers in modern S3 API specs). The application can simply request the file's metadata via a HeadObject API call to retrieve the remote hash and compare it with the local DB record.

4. Cloud Drives (Google Drive, OneDrive, Dropbox)

• Google Drive / OneDrive / Dropbox APIs: Their respective developer APIs expose file metadata that already includes a pre-computed hash of the file (e.g., md5Checksum for Google Drive, sha1Hash or quickXorHash for OneDrive/Dropbox). A simple API metadata fetch is enough to validate the file's integrity.

5. Legacy Protocols (FTP)

• FTP: For basic FTP servers that don't support remote execution, we could either:
  • Fall back to the Stream-based verification (streaming the file directly into a crypto hash in memory without writing to the local disk).
  • Use the FTP extension command XSHA256 or MD5 if the target FTP server supports it.

---

By mapping the integrity task behavior to the storage type, the application could safely run background checks for almost all protocols with near-zero network cost.

[Skyfay]

Thanks for this. I'll take a look into this in the next few days :)

[Skyfay]

Thanks for the detailed breakdown! The approach sounds straightforward at a high level, but there are a few implementation challenges worth noting:

• S3 ETags are not a reliable SHA-256 source, for multipart uploads they represent a composite hash, not the file's actual content hash. Proper S3 checksum verification would require storing a x-amz-checksum-sha256 at upload time, which means changes to the upload pipeline
• Remote SSH execution requires that the connection abstraction exposes a command channel, which our current SFTP adapter doesn't support yet
• Cloud Drive APIs (Google Drive, OneDrive) have inconsistencies, not all file types expose a usable content hash, and API availability varies

The cleanest solution would be extending the StorageAdapter interface with an optional verifyChecksum() method, letting each adapter implement the most efficient strategy for its protocol, and falling back to streaming verification for adapters that don't implement it.

That said, this is a meaningful improvement and I'll keep it on the roadmap, but it needs some deeper work rather than a quick add-on. I'll revisit this when I have the bandwidth.

In the same context, I would also like to add the ability to trigger a check for a single backup via the UI, and to see when the last check was performed. But all this stuff needs some time :)

[edmc73]

That makes perfect sense. You're completely right about the S3 multipart ETags and SFTP limitations—those are excellent points.

Extending the StorageAdapter interface with a verifyChecksum() method and a streaming fallback sounds like the perfect architectural approach. I'm also thrilled to hear that the UI button and timestamp ideas made it onto the roadmap.

Take all the time you need, and thank you for your awesome work on this app. Looking forward to testing it whenever it's ready!