# 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

```bash
# 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

```bash
go run cmd/backup/main.go -cleanup
```

#### List All Backups

```bash
go run cmd/backup/main.go -list
```

#### Default Action (Create + Cleanup)

```bash
go run cmd/backup/main.go
```

### Automated Scheduling

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

#### Cron Example

```bash
# 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`:

```ini
[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`:

```ini
[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:

```bash
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:

```bash
# 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