Backup Rotator#

Create, rotate, and verify backups with configurable retention policies. Uses only Python standard library — no pip install needed.

Quick start#

bash

# Create a backup
python3 skills/backup-rotator/scripts/backup_rotator.py --backup /path/to/source /path/to/backups

# Create backup with compress
python3 skills/backup-rotator/scripts/backup_rotator.py --backup /path/to/dir /backups --compress

# List existing backups
python3 skills/backup-rotator/scripts/backup_rotator.py --list /backups --name myproject

# Rotate (clean old backups)
python3 skills/backup-rotator/scripts/backup_rotator.py --rotate /backups --name myproject

# Dry run (see what would be deleted)
python3 skills/backup-rotator/scripts/backup_rotator.py --rotate /backups --name myproject --dry-run

# Verify backup integrity
python3 skills/backup-rotator/scripts/backup_rotator.py --verify /backups

Retention Policy (default)#

CategoryKeepDescriptionDaily7Most recent daily backupsWeekly4Most recent Sunday backupsMonthly3First 7 days of each monthOld0Beyond all retention → deleted

Default policy keeps 14 backups minimum.

Config File (for cron)#

Create a JSON config file for fully automated backup + rotation:

json

{
  "backup_source": "/var/lib/postgresql/database.dump",
  "backup_dest": "/backups/db",
  "backup_name": "postgres",
  "keep_daily": 7,
  "keep_weekly": 4,
  "keep_monthly": 3,
  "compress": true,
  "verify": true
}

Then run:

bash

python3 skills/backup-rotator/scripts/backup_rotator.py --cron config.json

Output:

text

  Backup Rotator — 2026-05-10 13:30:00
  ==================================================
  Name prefix:       postgres
  Keep daily:        7
  Keep weekly:       4
  Keep monthly:      3
  Compress:          yes
  Verify:            yes

  📦 Creating backup...
  Compressing /var/lib/postgresql/database.dump → /backups/db/postgres_20260510-133000.tar.gz
  Size:    42.3M
  SHA256:  a1b2c3d4e5f6...

  🔄 Rotating old backups...
  Summary: 12 keep, 3 delete
  Keeping:
    ✅ postgres_20260510-133000.tar.gz (42.3M) - keep (daily)
    ✅ postgres_20260509-020000.tar.gz (41.8M) - keep (daily)
    ...
  Deleting:
    🗑  postgres_20260428-020000.tar.gz (40.1M) - delete (past retention)

  ✅ Verifying remaining backups...
  ✅ postgres_20260510-133000.tar.gz SHA256: a1b2...
  ✅ postgres_20260509-020000.tar.gz SHA256: b2c3...

Common commands#

CommandAction--backup SOURCE DESTCreate timestamped backup--list DIRList all backups with age and category--rotate DIRApply retention policy, delete old backups--dry-runPreview rotation without deleting--verify DIRCheck SHA256 checksums of all backups--cron config.jsonFull automated run: backup + rotate + verify--name PREFIXFilter backup files by name prefix--compressCompress directory backups to tar.gz--no-verifySkip SHA256 verification

Automation with Cron#

Add to crontab for daily automated backups:

cron

# Daily at 2am
0 2 * * * cd /home/user && python3 skills/backup-rotator/scripts/backup_rotator.py --cron /home/user/configs/backup-postgres.json >> /var/log/backup-rotator.log 2>&1

Requirements#

• Python 3.6+ (no pip install needed)
• Uses only standard library: os, shutil, hashlib, json, argparse
• Works on Linux, macOS (partial)
• No external API calls — fully offline