Database Backup Policies
Overview
Database Backup Policies provide automated, offsite backups for managed databases with S3-compatible storage, incremental backups, and point-in-time recovery (PITR). Create reusable policies with S3 credentials, scheduling preferences, and retention settings, then attach one or more databases to each policy.
Key capabilities:
- S3-compatible storage -- Backups stream directly to any S3-compatible storage (AWS S3, MinIO, Wasabi, etc.)
- Engine-specific backups -- Uses the best backup tools for each engine (MySQL, MariaDB, PostgreSQL)
- Incremental backups -- Only back up changes since the last full backup, reducing storage and duration
- Point-in-time recovery (PITR) -- Recover to any second within the retention window using transaction log archiving
- AES-256 encryption -- Optional client-side encryption before upload
- Automatic failure handling -- Three consecutive failures pause the policy and notify you by email
- Reusable policies -- A single policy can be attached to multiple databases
Prerequisites
Before creating a backup policy:
- An S3-compatible storage bucket must be provisioned with valid access credentials (access key and secret key)
- At least one managed database must exist in Active status
- The S3 endpoint must be reachable from the database over HTTPS
S3 credentials require s3:PutObject, s3:GetObject, s3:DeleteObject, and s3:ListBucket permissions on the target bucket. Insufficient permissions will cause backup failures.
Creating a Backup Policy
User Panel
- Navigate to Databases > Backup Policies in the sidebar
- Click Add Policy
- Fill in the policy configuration:
General:
| Field | Description |
|---|---|
| Name | A descriptive name for the policy (e.g., "Production Daily") |
S3 Configuration:
| Field | Description |
|---|---|
| S3 Endpoint | Hostname of the S3-compatible endpoint (e.g., s3.us-east-1.amazonaws.com or minio.example.com) |
| S3 Bucket | Target bucket name |
| S3 Region | Bucket region (e.g., us-east-1) |
| S3 Access Key | IAM access key with read/write/delete permissions on the bucket |
| S3 Secret Key | Corresponding secret key |
| S3 Path Prefix | Optional prefix within the bucket (e.g., backups/production) |
Click Test Connection to verify S3 credentials before saving.
Schedule:
| Field | Values | Description |
|---|---|---|
| Full Backup Frequency | Daily, Weekly | How often a full backup runs |
| Full Backup Time | HH:MM (UTC) | Time of day to start full backups |
| Full Backup Day | Sunday -- Saturday | Day of week for weekly schedules |
| Incremental Frequency | None, 1h, 2h, 4h, 6h, 12h | Interval between incremental backups |
PITR:
| Field | Description |
|---|---|
| PITR Enabled | Toggle point-in-time recovery on or off |
When PITR is enabled, transaction log archiving (binary logs for MySQL/MariaDB, WAL archiving for PostgreSQL) is automatically configured when a database is attached to the policy. This allows recovery to any point in time within the retention window.
Retention:
| Field | Default | Description |
|---|---|---|
| Retain Full Backups | 7 | Number of full backups to keep |
| Retain Incrementals | 30 days | Days to retain incremental backups |
| Retain PITR | 72 hours | Hours to retain PITR archives |
Encryption:
| Field | Description |
|---|---|
| Encryption Enabled | Toggle AES-256 encryption for all backups (default: enabled) |
When encryption is enabled, the system auto-generates an encryption key that is stored securely. All backups are encrypted before upload.
- Click Create
Admin Panel
- Navigate to Managed Databases > Backup Policies
- Click Add Policy
- Select a User who will own the policy
- Fill in the same configuration sections as the user panel
- Click Create
Admins can view and manage all backup policies across all users.
Policy Detail Page
The policy detail page shows two sections:
Policy Summary
- Name and Status (Active, Paused, Error, or Validating)
- S3 Configuration -- Endpoint, bucket, region, and path prefix
- Credentials Verified -- Timestamp of last successful S3 validation
- Schedule -- Full backup frequency, time, and day (if weekly); incremental frequency
- Retention Settings -- Full backup count, incremental days, PITR hours
- Encryption -- Whether backups are encrypted
- Consecutive Failures -- Warning shown if failures have occurred
Attached Databases
A table listing all databases attached to this policy:
| Column | Description |
|---|---|
| Database Name | Name of the managed database |
| Engine | MySQL, MariaDB, or PostgreSQL |
| Host | Database hostname |
| Last Full Backup | Timestamp of most recent full backup |
| Last Incremental | Timestamp of most recent incremental backup |
| PITR Status | Active, Configuring, Error, or -- if disabled |
| Actions | Detach button |
Attaching Databases to a Policy
A database can be attached to exactly one backup policy at a time. Only primary databases in Active status can be attached.
From the Policy Detail Page
- Open the policy detail page
- In the Attached Databases section, select a database from the dropdown
- Click Attach
What Happens on Attach
When a database is attached:
- Backup tools are installed -- The required backup utilities are automatically installed on the database
- PITR is configured (if enabled on the policy) -- Transaction log archiving is set up for the database engine
- Initial full backup -- An immediate full backup runs to establish a baseline
The attach process may take a few minutes to complete, as it involves installing tools, configuring PITR, and running the initial full backup.
Detaching a Database
Click the Detach button next to the database on the policy detail page. PITR configuration is disabled on detach. Existing backups in S3 are not deleted.
Backup Types
Full Backups
Full backups capture the entire database state. They serve as the base for incremental chains and PITR recovery.
Incremental Backups
Incremental backups capture only changes since the last full backup, significantly reducing backup size and duration. If no parent full backup exists (e.g., it was deleted by retention cleanup), the system automatically falls back to a full backup.
PITR Archives
PITR archives are the continuous stream of transaction logs that enable recovery to any point in time:
- MySQL/MariaDB -- Binary logs are archived during each incremental backup job
- PostgreSQL -- WAL segments are archived continuously as they are generated
Backup Source Selection
The system automatically selects the best database to back up from:
- If the database has a healthy replica, the replica is used as the backup source to avoid performance impact on the primary
- If no healthy replica is available, the primary is used
This is fully automatic -- when a replica is available, backups run against the replica to minimize load on the primary.
Scheduling
Backups are scheduled automatically based on the policy configuration:
- Full backups run at the configured time and frequency (daily or weekly)
- Incremental backups run at the configured interval between full backups
- A database with a pending or in-progress backup is skipped to prevent overlap
Retention and Cleanup
Retention rules are enforced automatically on a daily basis:
| Rule | Description |
|---|---|
| Full backup count | Keeps the most recent N full backups, deletes older ones |
| Incremental age | Deletes incrementals older than the configured retention period |
| PITR archive age | Deletes PITR archives older than the configured retention period |
| Orphaned incrementals | Deletes incrementals whose parent full backup no longer exists |
When a full backup is deleted, all of its child incremental backups and associated PITR archives are also deleted from S3.
Restore Operations
Restore from Backup
Restore a database from a specific completed backup (full or incremental).
- On the database detail page, go to the Backups tab
- Click Restore next to the desired backup
- Confirm the action
For incremental restores, the system automatically applies the full backup plus each incremental in sequence.
Point-in-Time Recovery (PITR)
Restore a database to a specific timestamp within the PITR recovery window.
- On the database detail page, click Restore PITR
- Select the target date and time (the available recovery window is displayed)
- Click Restore
The system finds the most recent full backup before the target time, applies any incrementals, then replays transaction logs up to the exact target timestamp.
Restoring a database overwrites all current data. This operation cannot be undone. Consider creating a manual backup before performing a restore.
Manual Backup
Trigger an on-demand full backup from the policy detail page or the database manage page by clicking Manual Backup. A manual backup is rejected if a backup is already pending or in progress.
Failure Handling
| Event | Action |
|---|---|
| Single backup failure | Backup marked as failed, failure counter incremented, email notification sent |
| 3 consecutive failures | Policy paused, new backups stop scheduling, email notification sent |
| Backup succeeds | Failure counter resets, policy restored to active if it was paused |
| PITR gap detected | PITR status set to error, email notification sent |
| Backup source becomes unavailable | Next backup auto-selects a different source, email notification sent |
The policy detail page displays a warning banner when failures have occurred, showing the failure count and the last error message. A Reset Failures button allows clearing the counter and restoring the policy to Active status.
Email Notifications
Four email notifications are sent for backup-related events:
| Notification | Trigger |
|---|---|
| Backup Failed | Each individual backup failure |
| Policy Paused | Policy reaches 3 consecutive failures and is paused |
| PITR Gap Detected | Transaction log continuity is broken |
| Backup Source Changed | Backup source switched between replica and primary |
Admin vs. User Capabilities
| Capability | Admin | User |
|---|---|---|
| Create backup policies | Yes (for any user) | Yes (own only) |
| Edit/delete policies | Yes (any user's) | Yes (own only) |
| Attach/detach databases | Yes (any database) | Yes (own databases only) |
| View all policies | Yes (across all users) | Own policies only |
| Delete individual backups | Yes | Yes (own only) |
| Reset failure counter | Yes | Yes (own only) |
| Trigger manual backup | Yes | Yes (own only) |
| Restore from backup | Yes | Yes (own only) |
| PITR restore | Yes | Yes (own only) |
Troubleshooting
Policy stuck in "Error" status
The policy auto-pauses after 3 consecutive backup failures.
- Check the error message on the policy detail page
- Click Test Connection to verify S3 credentials are still valid
- Verify the database is running and reachable
- Click Reset Failures to resume the policy
Backup fails with "S3 upload failed"
- Verify S3 credentials are still valid (keys may have been rotated)
- Check that the S3 bucket exists and has the correct permissions
- For non-AWS endpoints (MinIO), verify the endpoint URL is correct and HTTPS is configured
PITR status shows "Error"
PITR errors indicate broken archive continuity. Use Retry PITR Configuration on the database detail page to re-deploy the PITR configuration.
Incremental backup falls back to full
This happens when the parent full backup was deleted by retention cleanup or had incomplete metadata. The system automatically runs a full backup instead to maintain backup chain integrity.
Restore fails
- Check the task status on the admin dashboard for error details
- Ensure sufficient disk space on the database for temporary restore files
- For PITR restores, recovery may take time if many transaction log segments need replaying
Cannot attach database: "Database is already attached to another backup policy"
A database can be attached to only one policy at a time. Detach the database from its current policy first, then attach it to the new one.