# Database Backups

URL: /docs/backups/database

Source: https://github.com/easypanel-io/monorepo/blob/main/apps/website/content/docs/backups/database.mdx

Schedule, run, retain, and restore logical database backups.



Easypanel creates logical backups for MySQL, MariaDB, PostgreSQL, and MongoDB
services. Each database service can have one or more backup configurations with
independent schedules, database names, destinations, and retention limits.

Redis does not have the scheduled database backup interface. Back up Redis
according to its configured persistence mode and test that recovery process
separately.

## Before you begin [#before-you-begin]

You need:

* a MySQL, MariaDB, PostgreSQL, or MongoDB service;
* a destination under the server's
  [**Settings → Storage Providers**](/docs/storage-providers);
* a database name that the database service can access;
* a license that includes scheduled database backups when you want Easypanel
  to run the configuration automatically.

Prefer remote storage to a local provider on the same server. Confirm that the
provider account can list, read, write, and delete objects in the selected
destination. Delete permission is needed when Easypanel enforces retention.

## Create a backup configuration [#create-a-backup-configuration]

1. Open the database service and select **Backups**.
2. Select **Create Database Backup**.
3. Enter the database name. Easypanel suggests databases it can discover, but
   you can enter another accessible name.
4. Enable the configuration when it should run automatically.
5. Select a schedule preset or enter a cron expression.
6. Optionally set **Retention** to the maximum number of backup files to keep.
7. Select a storage provider and enter a destination path.
8. Create the configuration.
9. Open its actions menu and select **Manual Run**.
10. Review **Backups Log**, then confirm the new file at the destination.

The default schedule is daily at `02:00`:

```text
0 2 * * *
```

Cron schedules follow the server's time. Check the server timezone before
choosing a production schedule.

Use a unique destination path for each database and configuration, for example:

```text
production/orders-postgres
```

## Backup files [#backup-files]

Easypanel uploads a timestamped file for every successful run:

| Service    | File extension | Backup tool                                   |
| ---------- | -------------- | --------------------------------------------- |
| MySQL      | `.sql.gz`      | `mysqldump`                                   |
| MariaDB    | `.sql.gz`      | `mariadb-dump`                                |
| PostgreSQL | `.sql.gz`      | `pg_dump` custom format, compressed with gzip |
| MongoDB    | `.archive.gz`  | `mongodump --gzip --archive`                  |

The action log records the database, storage provider, destination path, and
result of manual and scheduled runs. Give an optional manual run a name when
you need to associate it with a deployment or migration.

## Retention [#retention]

When **Retention** is set, Easypanel lists the files under the configured
destination path after a successful backup. It sorts them by modification time
and deletes the oldest files until the configured maximum remains.

<Callout type="warn">
  Retention considers all files in the configured destination path, not only
  files created by the current backup configuration. Never share that path with
  another backup or unrelated files.
</Callout>

A retention cleanup failure is reported in the action output but does not
invalidate a database dump that was uploaded successfully. Monitor destination
capacity and provider lifecycle rules in addition to the Easypanel limit.

## Run a backup manually [#run-a-backup-manually]

Open the configuration's actions menu and select **Manual Run**. A manual run
uses the same database, destination, and retention settings as the scheduled
job.

Run one manually:

* after creating or editing the configuration;
* before a destructive migration or major version upgrade;
* before changing credentials, storage, or the database image;
* when investigating a missed scheduled run.

Wait for a successful log entry and verify the object at the provider. Starting
an action is not proof that the upload completed.

## Restore a database backup [#restore-a-database-backup]

Restoration runs against the database service you currently have open and
replaces data in the database name you provide.

<Callout type="warn">
  A restore is destructive and runs in place. MySQL and MariaDB import the dump,
  PostgreSQL removes existing objects while restoring, and MongoDB drops
  matching collections. Take a fresh safety backup and verify the target
  service, database name, provider, and exact object path before continuing.
</Callout>

To restore:

1. Put the application in maintenance mode or stop processes that write to the
   database.
2. Open the database service's **Backups** tab.
3. Select **Restore**.
4. Select the storage provider.
5. Enter the exact path of the stored backup file, including its filename.
6. Enter the target database name.
7. Confirm the restore and follow its action output until completion.
8. Start the application and verify schema, record counts, authentication, and
   a representative read and write.

Practice this workflow with non-production data. A successful upload does not
guarantee that the backup contains the expected database or that the
application can use the restored state.

## Edit or remove a configuration [#edit-or-remove-a-configuration]

Editing changes future runs; it does not move or rename existing backup files.
After changing the database, provider, path, schedule, or retention, perform
another manual run.

Removing a configuration stops its schedule and removes it from Easypanel. It
does not delete files already stored at the provider.

## Troubleshooting [#troubleshooting]

When a run fails:

1. Open its entry in **Backups Log** and read the database, compression,
   transfer, and cleanup output.
2. Confirm that the [storage provider](/docs/storage-providers) still exists
   and that OAuth-based providers remain connected.
3. Check provider permissions and available storage.
4. Verify the database name and credentials by connecting from the database
   service's Shell menu.
5. Check the cron expression, enabled state, license, and server timezone for a
   schedule that does not start.
6. Run the configuration manually after correcting it.

If the dump succeeds but retention fails, inspect delete permission and make
sure the destination path contains only files owned by that configuration.