[v5.x] feat(backup): simplify v4 database backup functionality

[peaklabs-dev]

Why?

This PR introduces changes to v4.x backups required for the v5.x upgrade migration. It turns a high impact breaking change into a medium or even low impact breaking change.

In v5 we are removing legacy backup formats and legacy import logic because the backup and restore functionality will be more tightly coupled (consolidated onto a single page).
To facilitate this switch while maintaining the ability to restore some v4 backups in v5, we must adopt one (new) backup format now. This format will either remain fully compatible with v5 (no legacy restore options in v5) or transition to a single "legacy restore" option within v5 (instead of having 2 legacy restore options).

The current v4 backup and restore/ import logic is difficult to maintain and can be confusing for users, as it currently supports three different backup methods:

1. Backup all databases (dumpAll): This is likely the preferred option as it creates a backup of the entire database cluster (e.g., all PostgreSQL databases) and if you restore the one backup file, it will restore the entire cluster to a specific point in time (all databases).
   • Issue: The current import commands for this option are overcomplicated. -> Maybe the new commands will work for the old dumpAll files as well?
2. Default database backup: This is the current default option, which only creates a backup of the default database.
   • Issue 1: This is confusing, as restoring a backup will result in restoring only the default database rather than all data in all databases.
   • Issue 2: If you use Laravel for example, the default database name is often different. If you forget to change the name in your backup settings, your backups will not contain the actual database data (so you can not restore the DB).
   • Issue 3: When restoring you can accidentally overwrite the wrong database if you do not manually adjust the default command.
3. Databases To Backup option (databasesToBackup): This allows users to provide a comma-separated list of all databases they want to back up.
   • Issue 1: This creates separate backup files for each database, resulting in many files for multiple databases.
   • Issue 2: If you want to restore the entire database cluster to a specific point in time, you must import each database manually one by one.
   • Issue 3: The UX of inputing databases as a comma separated list is not optimal (validation, autocomplete, typos...).
   • Issue 4: If you add a new database to the cluster but forget to update this list, that data will not be backed up and cannot be restored.
   • Issue 5: When restoring one of these files, you can accidentally overwrite the wrong database if you do not manually adjust the default command.

Summary

• Approach 1 is probably the approach most users expect when backing up a database container. A full backup of the entire cluster, not just a partial backup of a database.
• Approach 2 only makes sense if you have a single database. However, if you have a single database you could use approach 1 with no meaningful difference in size or performance.
• Approach 3 has many issues that can be solved by simply using approach 1 and backing up everything.

The New Approach

• The new backup system for v4 significantly simplifies the backup workflow. You can simply enable backups without needing to select what to back up. In the background Coolify will always back up the full database cluster.
• This also simplifies backup restores as you can restore the entire database cluster to a specific point in time with a single click and 1 file.

Drawbacks

• A user can no longer selectively restore a single table (pg_restore could do that)
• A user can also no longer selectively just restore a single database.
• If you have multiple large databases and want to exclude one from the backup, this is no longer possible when we always backup all databases for most DBs at least (Postgres has an option to exclude a database but most DBs do not).
• Dumping a single database allows parallelization (so it can be faster).
• Using pg_restore allows parallelization for restores (so it can be faster).

Before vs. After

Before	After

Changes

• feat(backup): remove overcomplicated backup settings with dumpAll and databasesToBackup options as we now always just backup all databases inside a cluster
• feat(backup): always backup all databases with the backup job, which makes it easier to maintain
• feat(backup): add new much simpler backup restore commands
• feat(api): remove dump_all and databases_to_backup from api
• feat(backup): mark all existing backups as legacy backups
• feat(ui): add legacy badge to backup executions ui and remove database
• feat(ui): add legacy import command options to the ui
• feat(notifications): use just the coolify database name in notifications and no longer the database_name of the cluster

[ShadowArcanist]

Peak doing Peaky stuffs! LGTM!!!

[priard]

Thanks a lot for the detailed write‑up and for putting so much thought into simplifying the backup UX. I completely understand the motivation to reduce confusion and maintenance overhead, and I agree that for many users “backup the whole cluster” is the most intuitive mental model.

That said, I’m struggling with the idea of completely removing the ability to control what gets backed up and restored. It feels like we’re optimising strongly for simplicity at the cost of flexibility in more advanced, but still very realistic, setups.

A concrete example: multiple applications or sites sharing a single database cluster. Imagine three news sites, each living in its own database within the same cluster. With the new approach, if one site has a problem and we need to restore just that one database, we can only restore the entire cluster. That means rolling back data for all three sites, potentially undoing work from multiple teams that didn’t need to be touched at all. In many environments, that’s not acceptable operationally.

On top of that, the “dump everything” approach can become quite heavy in scenarios with several large databases in a single cluster. A full‑cluster dump may be huge, slower to create, slower to transfer and slower to restore, even when the incident concerns only a small subset of that data. In those cases, being able to narrow the scope of what gets backed up and restored is not only about flexibility, but also about performance, cost and operational practicality.

Some additional concerns that come to mind:

• In multi‑tenant or multi‑project clusters, selectively restoring a single database (or even a subset of data) is an important safety valve. Without it, every restore becomes a “big hammer” operation with much higher blast radius.
• From a performance and cost perspective, backing up and restoring the entire cluster can be overkill when you have one or two “heavy” databases and several small ones. Sometimes you explicitly don’t want to include a big analytics/archival DB in frequent backups.
• For compliance or internal policy reasons, teams may be required to treat certain databases differently (e.g. different retention, different RPO/RTO), which becomes harder if everything is always backed up as a single unit.
• For testing and development workflows, it’s often useful to restore just one database into a staging environment without touching the rest of the cluster. Losing an easy path for that will push people to build bespoke scripts and tooling outside of Coolify.

I’m not arguing against the simplified “backup everything” as a default – I think that’s a good change for most users. My concern is that removing the more granular controls entirely will force more advanced users to bypass Coolify’s backup system altogether (custom scripts, external tools, etc.), which is also not ideal for maintainability or support.

Maybe a middle ground would be to keep the simple “backup whole cluster” path as the default, and expose some form of “advanced mode” or expert toggle for the people who really know what they’re doing. That could be as small as:

• an option to selectively restore a single database from a cluster backup, and/or
• a way to exclude specific databases from backup on clusters where that’s really needed,

even if these options are not front‑and‑centre in the main UI and perhaps only show up behind an “Advanced” switch or via API/CLI. That way, the vast majority of users get the streamlined experience you’re aiming for, while more complex but common setups are still supported without forcing people to completely leave Coolify’s backup features.

Curious what you think about keeping the simple default while preserving a bit of advanced flexibility for these scenarios.

[peaklabs-dev]

Superseded by #9660