veza/veza-backend-api/docs/BACKUP_STRATEGY.md

Database Backup Strategy

Overview

This document describes the automated database backup strategy implemented for the Veza backend API.

BE-DB-016: Automated Database Backups with Retention Policy

Features

• Automated Backups: Create full database backups using PostgreSQL's pg_dump
• Retention Policy: Automatically clean up old backups based on configurable retention period
• Compressed Format: Backups use PostgreSQL's custom format (-Fc) for efficient storage
• CLI Tool: Command-line tool for manual backup operations

Configuration

Backup configuration can be set via environment variables or command-line flags:

• BACKUP_DIR: Directory to store backups (default: /backups/postgres)
• BACKUP_RETENTION_DAYS: Number of days to retain backups (default: 30)
• DATABASE_URL: PostgreSQL connection URL
• PGPASSWORD: PostgreSQL password (if not in DATABASE_URL)

Usage

Create a Backup

# Using the backup CLI tool
go run cmd/backup/main.go -create

# Or with custom settings
go run cmd/backup/main.go -create -backup-dir=/var/backups -retention-days=60

Cleanup Old Backups

go run cmd/backup/main.go -cleanup

List All Backups

go run cmd/backup/main.go -list

Default Action (Create + Cleanup)

go run cmd/backup/main.go

Automated Scheduling

For production environments, set up a cron job or systemd timer:

Cron Example

# Daily backup at 3 AM
0 3 * * * /path/to/veza-backend-api/cmd/backup/main.go -create -cleanup

Systemd Timer Example

Create /etc/systemd/system/veza-backup.service:

[Unit]
Description=Veza Database Backup
After=network.target

[Service]
Type=oneshot
ExecStart=/path/to/veza-backend-api/cmd/backup/main.go -create -cleanup
Environment="DATABASE_URL=postgres://user:pass@host:5432/veza_db"
Environment="BACKUP_DIR=/var/backups/postgres"
Environment="BACKUP_RETENTION_DAYS=30"

Create /etc/systemd/system/veza-backup.timer:

[Unit]
Description=Veza Database Backup Timer
Requires=veza-backup.service

[Timer]
OnCalendar=daily
OnCalendar=03:00
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

sudo systemctl enable veza-backup.timer
sudo systemctl start veza-backup.timer

Backup Format

Backups are created using PostgreSQL's custom format (-Fc), which provides:

• Compression: Automatic compression to reduce storage space
• Parallel Restore: Can be restored in parallel for faster recovery
• Selective Restore: Can restore specific tables or schemas

Retention Policy

The default retention policy is 30 days. Backups older than the retention period are automatically deleted during cleanup operations.

Restore Procedure

To restore a backup:

# Using pg_restore
pg_restore -d veza_db /backups/postgres/veza_db_20240101_030000.sql

# Or from custom format
pg_restore -d veza_db -Fc /backups/postgres/veza_db_20240101_030000.dump

Best Practices

1. Regular Backups: Schedule daily backups during low-traffic periods
2. Off-Site Storage: Copy backups to remote storage (S3, etc.) for disaster recovery
3. Test Restores: Periodically test restore procedures to ensure backups are valid
4. Monitor Backup Size: Monitor backup sizes to detect unusual growth
5. Encryption: Consider encrypting backups for sensitive data
6. Retention: Adjust retention period based on compliance requirements

Monitoring

Monitor backup operations by checking:

• Backup file sizes (should be relatively consistent)
• Backup creation timestamps
• Cleanup operation logs
• Disk space usage in backup directory

Troubleshooting

Backup fails with "pg_dump: command not found"

• Install PostgreSQL client tools: apt-get install postgresql-client (Debian/Ubuntu) or yum install postgresql (RHEL/CentOS)

Backup fails with authentication error

• Ensure DATABASE_URL or PGPASSWORD is set correctly
• Verify database user has necessary permissions

Backup directory not writable

• Check directory permissions: chmod 755 /backups/postgres
• Ensure backup service runs with appropriate user permissions