Backup Management
Relevant source files
The following files were used as context for generating this wiki page:
The Backup Management system in Percona Monitoring and Management (PMM) provides a robust framework for performing, scheduling, and managing database backups across supported vendors including MySQL and MongoDB. It enables users to ensure data durability through on-demand snapshots, scheduled recurring tasks, and Point-in-Time Recovery (PITR) capabilities. The system integrates closely with PMM Server for orchestration and pmm-agent for execution on monitored nodes.
Sources: api/backup/v1/backup.proto:200-264, ui/apps/pmm/src/pages/settings/Settings.messages.ts:68-71, README.md:31-35
System Architecture and Data Flow
The architecture follows a request-response pattern where the PMM Server orchestrates backup jobs by communicating with pmm-agent instances located on the database nodes. Backup artifacts are stored in configured locations such as S3-compatible storage or local filesystems.
The diagram shows the flow from a user request to the final storage of a backup artifact.
Sources: api/agent/v1/agent.proto:430-460, CONTRIBUTING.md:28-45, managed/services/management/backup/backup_service_test.go:170-190
Core Components
- BackupService: The primary gRPC service defining operations for starting backups, listing artifacts, and managing schedules.
- pmm-agent: Receives
StartJobRequestmessages to execute vendor-specific tools likextrabackupfor MySQL orpbm(Percona Backup for MongoDB). - Artifacts: Represent the result of a backup operation, containing metadata such as file lists, data models, and creation timestamps.
Sources: api/backup/v1/backup.proto:200-264, api/agent/v1/agent.proto:415-430, api/backup/v1/backup.swagger.json:280-325
Backup Operations
Users can initiate backups either on-demand or through persistent schedules. The system supports various data models and modes depending on the database vendor.
Backup Modes and Models
| Type | Enumerations | Description |
|---|---|---|
| Data Model | PHYSICAL, LOGICAL | Specifies if the backup is a file-level copy or a logical export. |
| Backup Mode | SNAPSHOT, INCREMENTAL, PITR | Defines the strategy (full state, changes only, or continuous stream). |
Sources: api/backup/v1/common.proto:7-21, api/backup/v1/backup.proto:11-23
Point-in-Time Recovery (PITR)
For MongoDB, the system supports PITR through PBM. This requires a logical data model. Enabling PITR for a cluster imposes constraints: only one PITR schedule can be enabled for a specific cluster at a time to prevent stream conflicts.
Sources: managed/services/management/backup/backup_service_test.go:273-288, api-tests/backup/backup_test.go:226-258
Job Execution and Logging
When a backup starts, PMM generates a unique job_id. The pmm-agent streams logs back to the server in chunks, allowing real-time monitoring of the backup progress.
This sequence illustrates the communication between the server and agent during an active backup job.
Sources: api/agent/v1/agent.proto:415-560, api/backup/v1/backup.proto:186-198
Error Handling
The system categorizes errors using specific codes to assist in troubleshooting, particularly for tool-related issues.
ERROR_CODE_XTRABACKUP_NOT_INSTALLEDERROR_CODE_INVALID_XTRABACKUP(Version mismatch)ERROR_CODE_INCOMPATIBLE_XTRABACKUP
Sources: api/backup/v1/backup.proto:205-210, managed/services/management/backup/backup_service_test.go:88-105
Scheduling Management
Schedules are defined using cron expressions. The system tracks the last_run and next_run times and supports automatic retries with configurable intervals.
Schedule Configuration Fields
| Parameter | Type | Description |
|---|---|---|
cron_expression | string | Standard cron format for recurrence. |
retention | uint32 | Number of artifacts to keep (0 for unlimited). |
retries | uint32 | Number of retry attempts on failure. |
retry_interval | Duration | Delay between retry attempts (e.g., "1m", "1h"). |
Sources: api/backup/v1/backup.proto:61-105, api-tests/backup/backup_test.go:115-135
Implementation Details: MongoDB vs MySQL
Backup implementation varies significantly based on the database vendor and the underlying tools utilized by the agent.
MongoDB (PBM)
MongoDB backups utilize pbm metadata. The system can retrieve specific PITR timeranges available in a storage location to facilitate recovery to a specific timestamp.
Sources: api/backup/v1/common.proto:28-32, managed/services/management/backup/backup_service_test.go:343-370
MySQL (XtraBackup)
MySQL backups rely on the Percona XtraBackup tool. Key parameters for the agent include database DSN, socket paths, and S3 credentials for direct upload.
Sources: api/agent/v1/agent.proto:430-455, managed/services/management/backup/backup_service_test.go:75-85
Summary
Backup Management in PMM serves as a centralized control plane for database protection. By abstracting tool-specific complexities into a unified API and leveraging pmm-agent for local execution, it provides a consistent interface for managing snapshots and point-in-time recovery across diverse database environments.
Sources: CONTRIBUTING.md:1-20, api/backup/v1/backup.swagger.json:1-50