Skip to content

feat: Integrate pgBackRest for PostgreSQL backups#8413

Closed
285729101 wants to merge 1 commit intocoollabsio:v4.xfrom
285729101:feat/pgbackrest-integration
Closed

feat: Integrate pgBackRest for PostgreSQL backups#8413
285729101 wants to merge 1 commit intocoollabsio:v4.xfrom
285729101:feat/pgbackrest-integration

Conversation

@285729101
Copy link
Copy Markdown

Summary

Implements pgBackRest integration for PostgreSQL databases in Coolify, addressing the need for efficient incremental backups for large databases (100GB+). This replaces the standard pg_dump approach (when enabled) with pgBackRest's WAL-based backup system, which supports:

  • Full, differential, and incremental backups - dramatically reducing backup time and S3 storage costs for large databases
  • S3/MinIO backup destinations - pgBackRest writes directly to S3-compatible storage without intermediate local storage
  • WAL archiving - enables continuous archiving and point-in-time recovery
  • Built-in retention management - pgBackRest handles retention of full and differential backups natively
  • Restore functionality - one-click restore from the UI or API with automatic PostgreSQL restart

Changes

New files:

  • app/Jobs/PgBackRestBackupJob.php - Backup job that installs pgBackRest in the PG container, configures WAL archiving, creates stanzas, and runs full/diff/incr backups
  • app/Jobs/PgBackRestRestoreJob.php - Restore job that stops PG, runs pgBackRest delta restore, and restarts the database
  • database/migrations/2026_02_17_000002_add_pgbackrest_to_scheduled_database_backups.php - Adds pgBackRest config columns (backup type, retention, S3 credentials)
  • tests/Feature/PgBackRestBackupTest.php - Feature tests for migration, model casts, job classes, and API validation

Modified files:

  • app/Models/ScheduledDatabaseBackup.php - Added casts for pgBackRest boolean and encrypted S3 credentials
  • app/Livewire/Project/Database/BackupEdit.php - Added pgBackRest configuration properties, sync logic, restore action, and info viewer
  • app/Livewire/Project/Database/BackupNow.php - Dispatches PgBackRestBackupJob when pgBackRest is enabled
  • app/Livewire/Project/Database/CreateScheduledBackup.php - Added pgBackRest toggle for PostgreSQL databases
  • app/Jobs/ScheduledJobManager.php - Routes to correct job class based on use_pgbackrest flag
  • app/Console/Commands/RunScheduledJobsManually.php - Same routing for manual job dispatch
  • app/Http/Controllers/Api/DatabasesController.php - Added pgBackRest fields to backup create/update API validation and dispatch
  • routes/api.php - Added POST /databases/{uuid}/backups/{id}/restore endpoint
  • resources/views/livewire/project/database/backup-edit.blade.php - Full pgBackRest UI section with backup type, retention, S3 config, info viewer, and restore button
  • resources/views/livewire/project/database/create-scheduled-backup.blade.php - pgBackRest checkbox for PostgreSQL

How it works

  1. User creates a backup schedule for a PostgreSQL database and enables pgBackRest
  2. On first backup run, pgBackRest is installed in the PG container, WAL archiving is configured, and a stanza is created
  3. Subsequent runs perform the configured backup type (full/diff/incr)
  4. pgBackRest manages its own retention policy for full and differential backups
  5. Users can view backup info and trigger restores from the UI or API
  6. S3/MinIO credentials are encrypted at rest in the database

Closes #7423

Test plan

  • Create a PostgreSQL database in Coolify
  • Create a scheduled backup with pgBackRest enabled (local repo type)
  • Run backup manually and verify it completes successfully
  • Run a differential backup after the initial full backup
  • Verify backup info shows correct stanza and backup details
  • Test restore functionality
  • Test with S3/MinIO repository type
  • Test API endpoints for creating/updating pgBackRest backup configs
  • Test API restore endpoint
  • Verify standard pg_dump backups still work when pgBackRest is not enabled
  • Test with large databases (100GB+) to verify incremental efficiency

🤖 Generated with Claude Code

Add pgBackRest as an alternative backup method for PostgreSQL databases,
enabling efficient incremental and differential backups. This is
particularly beneficial for large databases (100GB+) where pg_dump
becomes impractical due to time and storage costs.

Changes:
- Add PgBackRestBackupJob with WAL archiving, stanza management,
  and full/differential/incremental backup support
- Add PgBackRestRestoreJob for point-in-time and labeled restores
- Add migration for pgBackRest configuration fields on
  scheduled_database_backups table (backup type, retention,
  S3/MinIO repo configuration)
- Update BackupEdit Livewire component with pgBackRest UI controls
  including backup type selection, retention settings, S3 config,
  backup info viewer, and restore button
- Update CreateScheduledBackup to offer pgBackRest option for
  PostgreSQL databases
- Update BackupNow to dispatch correct job based on configuration
- Update ScheduledJobManager and RunScheduledJobsManually to
  dispatch PgBackRestBackupJob when use_pgbackrest is enabled
- Add API support for pgBackRest fields in backup CRUD endpoints
- Add POST /databases/{uuid}/backups/{id}/restore API endpoint
- Encrypt S3 credentials (pgbackrest_s3_key, pgbackrest_s3_secret)
- Add comprehensive feature tests

Closes coollabsio#7423
@github-actions
Copy link
Copy Markdown
Contributor

This PR did not pass quality checks so it will be closed. If you believe this is a mistake please let us know.

@github-actions github-actions bot closed this Feb 17, 2026
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 20, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Enhancement]: Use pgBackRest for Postgres backups

1 participant