Skip to content

[v5.x] feat(backup): standardize v4 database backups#9660

Draft
peaklabs-dev wants to merge 14 commits intonextfrom
v5.x-feat/standardize-database-backups
Draft

[v5.x] feat(backup): standardize v4 database backups#9660
peaklabs-dev wants to merge 14 commits intonextfrom
v5.x-feat/standardize-database-backups

Conversation

@peaklabs-dev
Copy link
Copy Markdown
Member

@peaklabs-dev peaklabs-dev commented Apr 19, 2026

Why?

This PR standardizes the v4.x database backup format to prepare for the v5.x upgrade migration, turning what would be a high-impact breaking change into a low-impact one.

In v5, backup and restore will be consolidated onto a single page. Legacy backup formats, the import page and legacy import logic will be removed entirely.

To facilitate this switch while maintaining the ability to restore some v4 backups in v5 the backup format needs to be standardized now in v4 so that backups created after this change are directly compatible with v5.

PR #8131 documents the problems with the current backup system in detail (3 different backup methods, confusing defaults, overcomplicated restores). That PR solved it by removing the per-database backup option entirely and always backing up all databases. While that simplified things, it introduced drawbacks that matter in practice:

  • Users with large clusters cannot exclude databases they don't need, wasting storage and backup execution time.
  • Restoring a single database requires restoring the entire cluster, which is more destructive and slower. For example, restoring a corrupted database would also overwrite every other database in the cluster with potentially stale data.
  • Per-database dumps preserve granular restore capabilities that full-cluster dumps lose: pg_restore --table can restore a single table, for example.

This PR takes a different approach that standardizes the format without removing flexibility:

  • "Backup all databases" becomes the default. This is the easiest, recommend and safest option for most users. Existing backup jobs without specified databases are migrated to this default to simplify the backup job UI.
    • No configuration needed
    • No risk of forgetting a database
    • Restoring always restores all databases
  • The individual database(s) backup feature stays but produces 1 single archive (v5 format). When users specify databases, each is dumped individually and bundled into one .tar.gz archive.
    • This means one backup execution per scheduled run (not one per database) - which is better UX.
    • Cleaner execution history
    • And especially on v5 much simpler restores with a multi select for which database to restore and an optional table input.
  • Old per-database backups are marked as legacy. But the backup files (.dmp and .sql) remain fully restorable in v4. They are marked as legacy now as these files will not be migrated over to v5.

Changes

  • Default new backup job schedules to "backup all databases"
  • Migrate existing backup schedules that have no databases_to_backup (empty or null) to dump_all = true
  • Standardize the backup job
    • When one database or multiple are listed for backup, back them up one by one and then bundle them into an archive. This eliminates multiple execution logs per backup (previously one for each database backed up) and consolidates them into a single execution regardless of how many separate databases are backed up, making backups and restores simpler and preparing for v5
    • Fixes mongo:4 single-DB backups dumping all databases instead of the selected one (missing --db flag)
    • Fixes mariadb dump_all backup output not being compressed despite .gz extension (--compress does not compress output)
    • Removes --compress from mysql dump_all backup (already gzipped)
    • Simplify databasesToBackup parsing
  • Add improved restore functionality
    • Add new restore commands to restore one or more databases from an archive (v5 format)
    • Move single database restore command into a legacy option
    • Improve ui with a select component instead of checkboxes
    • Fixes postgres restore failing when the default database does not exist (use template1 which is guaranteed to exist)
    • Fixes mysql/mariadb dump_all restore piping all databases into one target database instead of restoring each to its own
  • Mark existing single-database backup executions as legacy
    • Add legacy badge with helper tooltip to the backup executions UI
  • Update backup job settings UI
    • Add dump_all checkbox to MongoDB (previously used empty databases_to_backup to mean "all")
    • Add or improve helper text for all backup settings
    • Make "databases to backup" required when dump_all is disabled
  • Rename backup executions database_name column to databases
    • One backup execution can now contain multiple databases, not just one. Therefore, we will store the database names or "all" in this column instead of just one database per backup execution.
  • Align backup api endpoints with standardized backup logic
  • Allow custom classes on the helper popup component

Supersedes

- One backup job can now contain multiple databases, not just one. Therefore, we will store the database names or "all" in this column instead of just one database per backup execution.
- when one database or multiple are listed for backup, back them up one by one and then bundle them into an archive. This eliminates multiple execution logs per backup (previously one for each database backed up) and consolidates them into a single execution regardless of how many separate databases are backed up, making backups and restores simpler and preparing for v5
- fixes mongo:4 single-DB backups dumping all databases instead of the selected one (missing --db flag)
- fixes mariadb dump_all backup output not being compressed despite .gz extension (--compress does not compress output)
- removes --compress from mysql dump_all backup (already gzipped)
- remove unused code
- in previous versions, mongodb used empty databases_to_backup to dump all DBs. This is weird and it should better be like the other databases using the dump_all flag.
- add or improve backup settings helper text
- make database to backup required if dumpAll is false
- add new restore commands to restore one or more databases from an archive
- move single database restore command into a legacy option
- improve ui with a select component instead of checkboxes
- fixes postgres restore failing when the default database does not exist (use template1 which is guaranteed to exist)
- fixes mysql/mariadb dump_all restore piping all databases into one target database instead of restoring each to its own
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant