# Restorex — Automated Database Backup Engine

> Automated backup engine with smart change detection, real-time dashboard, and Docker deployment. Protect your databases while you sleep.

Website: https://restorex-landing.vercel.app
GitHub: https://github.com/DeSebasWeb/restorex
License: MIT (free and open source)

## What is Restorex?

Restorex is an open-source, self-hosted backup engine for PostgreSQL databases. It connects to your server via SSH, detects which databases have changed since the last backup, and only backs up those — saving time, bandwidth, and storage. Everything is managed through a professional React dashboard.

## Origin Story

I had 24 production databases with no automated backup. I built Restorex, ran it overnight, and woke up to everything safely backed up. That's the problem it solves.

24 databases. One night. Zero data loss.

## Key Features

1. **Smart Change Detection** — Queries pg_stat_user_tables to detect INSERTs, UPDATEs, and DELETEs since last backup. Unchanged databases are skipped automatically. New databases are always backed up on first run.
2. **Real-time Dashboard** — React 19 + TypeScript + Tailwind CSS 4. Live progress bars, download percentages per database, backup history, executive reports. Dark and light mode included.
3. **Notifications** — Slack (webhooks), Telegram (Bot API), Email (SMTP). Per-channel triggers: success, failure, partial. Configure exactly what you want to hear about. Credentials encrypted at rest with AES-256 (Fernet).
4. **Parallel Backups** — Configurable number of concurrent workers (1-10). Each worker gets its own SSH connection for thread safety. Expandable progress UI shows all active jobs.
5. **Automatic Scheduling** — Built-in APScheduler for daily backups at configured time. Manual backup available anytime via dashboard or CLI.
6. **Dual Format Output** — Every backup generates .backup (PostgreSQL custom format, compressed, supports parallel restore) and optionally .sql.gz (gzipped plain SQL, human-readable). SQL generation is toggleable from Settings.
7. **Secure by Design** — SSH tunnels with host key verification (saved to known_hosts), all shell arguments escaped with shlex.quote(), remote file cleanup via SFTP (not shell rm), path validation (only deletes inside /tmp/pg_backups/), database names validated with DbName value object (regex, max 63 chars). Zero shell injection.
8. **Multi-Engine Ready** — PostgreSQL today. MySQL, MongoDB, and SQL Server coming soon. Hexagonal architecture (ports & adapters) makes it easy to add new database engines without rewriting infrastructure.
9. **Docker Ready** — One command deployment: `docker compose up -d`. Backend API + React frontend + nginx reverse proxy, all containerized.
10. **Full Configuration from UI** — No need to edit .env files. Configure SSH, PostgreSQL, backup directory, retention days, schedule time, parallel workers, and SQL generation — all from the Settings page. Test connection with one click.
11. **MCP Server (Coming Soon)** — Connect any MCP-compatible AI (Claude, Cursor, or custom agents) to manage backups through natural language. Ask "Which databases failed backup last night?" or "Run a backup of ecommerce_production now."

## Tech Stack

- **Frontend**: React 19, Vite 8, TypeScript, Tailwind CSS 4
- **Backend**: Python, Flask 3, Flask-CORS, SQLAlchemy 2
- **SSH/SFTP**: Paramiko (with keepalive every 30s, host key verification)
- **Database**: PostgreSQL (local, for app metadata — history, settings, stats)
- **Scheduler**: APScheduler
- **Encryption**: Fernet (AES-128-CBC + HMAC-SHA256) via cryptography library
- **Deployment**: Docker Compose, nginx
- **Architecture**: Hexagonal (ports & adapters), dependency injection via Container pattern

## Architecture

Built with hexagonal architecture (ports & adapters). The domain layer has zero external dependencies.

```
backend/src/
├── domain/                    # Business core — 0 dependencies
│   ├── entities/              # BackupRecord, DatabaseInfo
│   ├── ports/                 # Interfaces (RemoteExecutor, FileTransfer,
│   │                          #   DatabaseInspector, Filesystem, BackupRepository,
│   │                          #   NotificationSender)
│   ├── value_objects/         # BackupFormat, DbChangeStats, DbName
│   └── exceptions.py
│
├── application/               # Use cases — depends only on domain
│   ├── services/              # BackupService, ReportService, NotificationService
│   └── dto/                   # BackupResultDTO, BackupSummaryDTO, DatabaseStatusDTO
│
├── infrastructure/            # Output adapters — implements ports
│   ├── adapters/              # SSHAdapter, PostgresAdapter, FilesystemAdapter,
│   │                          #   SlackNotifier, TelegramNotifier, EmailNotifier
│   ├── database/models/       # SQLAlchemy models (1 file per model)
│   ├── persistence/           # PostgresBackupRepository, SettingsRepository,
│   │                          #   ProgressTracker, NotificationRepository
│   ├── security/              # Fernet encryption service
│   └── config.py              # Settings (DB > .env > defaults)
│
├── entry_points/              # Input adapters
│   ├── api/app.py             # Flask REST API
│   ├── cli.py                 # Terminal execution
│   └── scheduler.py           # APScheduler (daily backup)
│
└── container.py               # Dependency injection

frontend/src/
├── components/                # Sidebar, TopBar, StatCard, ProgressRing,
│                              #   BackupProgressBar (expandable), StatusDot, Toast
├── pages/                     # Dashboard, Databases, History, Reports, Logs,
│                              #   Settings, Notifications
├── hooks/                     # useBackupStatus, useTheme
├── services/api.ts            # Typed HTTP client with timeout + error handling
├── types/index.ts             # TypeScript interfaces
└── utils/format.ts            # Shared formatters
```

## Quick Start

```bash
git clone https://github.com/DeSebasWeb/restorex.git
cd restorex
cp backend/.env.example backend/.env   # Edit with your local DB URL
docker compose up --build -d
```

Open http://localhost:3000 → Go to Settings → Enter SSH/PostgreSQL credentials → Test Connection → Scan DBs → Smart Backup

Requirements: Docker Desktop + PostgreSQL running locally (for app metadata)

## How It Works

1. Connect to your remote server via SSH (through VPN if needed)
2. Discover all PostgreSQL databases (excludes template0, template1, postgres)
3. Compare current pg_stat_user_tables stats with last backup stats to detect changes
4. For each database that needs backup:
   - If never backed up → backup always (first run)
   - If already backed up → only if changes detected (INSERT/UPDATE/DELETE counts differ)
   - Generate .backup file via pg_dump -Fc (custom format, compressed)
   - Optionally generate .sql.gz via pg_dump -Fp | gzip (if enabled)
   - Download via SFTP with real-time progress tracking (bytes/total)
   - Clean up temporary files on server
5. Rotate local backups older than retention period (default: 7 days)
6. Save run history to local PostgreSQL
7. Send notifications to configured channels (Slack, Telegram, Email)

## Pricing

- **Community (Free forever)**: 1 server connection, PostgreSQL support, local backups, 7-day retention, full dashboard + reports, Docker deployment
- **Pro ($9/month, coming soon)**: Unlimited servers, multi-engine (MySQL, MongoDB), cloud backups (S3, GCS), Slack/Email/Telegram alerts, 90-day retention, MCP server for AI agents, priority support
- **Cloud ($29/month, coming soon)**: Everything in Pro + managed hosting, no Docker needed, custom domain, team access & roles, API keys, SLA guarantee

## Comparison vs Alternatives

| Feature                    | Restorex | pgBackRest | Barman  |
|---------------------------|----------|------------|---------|
| Setup time                | 2 min    | Hours      | Hours   |
| Visual dashboard          | Yes      | No         | No      |
| Smart change detection    | Yes      | No         | No      |
| Telegram/Slack/Email      | Yes      | No         | Limited |
| AI agent integration (MCP)| Soon     | No         | No      |
| Self-hosted               | Yes      | Yes        | Yes     |
| Free & open source        | Yes      | Yes        | Yes     |

## Production Stats

- 26+ databases managed in production
- 2TB+ of data protected
- 99.9% backup success rate
- <2 minutes from git clone to first backup

## API Endpoints

All endpoints return JSON. The frontend communicates exclusively through this API.

| Method | Endpoint                      | Description                              |
|--------|-------------------------------|------------------------------------------|
| GET    | /api/health                   | Health check + configuration status      |
| GET    | /api/status                   | All databases with stats and backup info |
| GET    | /api/history                  | Backup run history (last 50 runs)        |
| POST   | /api/backup/run               | Start backup ({ "force": false })        |
| GET    | /api/backup/status            | Running state + live progress + active jobs |
| POST   | /api/scan                     | Discover databases on remote server      |
| GET    | /api/report                   | Executive report with KPIs               |
| GET    | /api/logs                     | Application logs (last 100 lines)        |
| GET    | /api/settings                 | Current configuration (passwords masked) |
| POST   | /api/settings                 | Save configuration + rebuild DI container |
| POST   | /api/settings/test-connection | Test SSH + PostgreSQL connectivity       |
| GET    | /api/notifications            | Notification channel configurations      |
| POST   | /api/notifications            | Save notification channel config         |
| POST   | /api/notifications/:ch/test   | Send test notification to channel        |

## Configuration (all configurable from dashboard Settings page)

| Setting           | Description                                    | Default           |
|-------------------|------------------------------------------------|-------------------|
| SSH Host          | Remote server IP (via VPN)                     | —                 |
| SSH Port          | SSH port                                       | 22                |
| SSH User/Password | SSH credentials                                | —                 |
| PG Host           | PostgreSQL host (from server perspective)       | localhost         |
| PG Port           | PostgreSQL port                                | 5432              |
| PG User/Password  | Database credentials                           | —                 |
| Backup Directory  | Local backup path (inside Docker)              | /backups/databases|
| Remote Temp Dir   | Temp directory on remote server                | /tmp/pg_backups   |
| Retention Days    | Auto-delete backups older than N days          | 7                 |
| Schedule Hour/Min | Daily automatic backup time                    | 23:00             |
| Generate SQL      | Create .sql.gz in addition to .backup          | true              |
| Parallel Workers  | Number of concurrent backup jobs (1-10)        | 3                 |

## Roadmap

- [ ] Multi-engine support (MySQL, MongoDB, SQL Server)
- [ ] MCP server for AI agent integration
- [ ] Cloud backup destinations (S3, Google Cloud Storage)
- [ ] Multi-server monitoring from single dashboard
- [ ] Backup encryption at rest
- [ ] Authentication & team access
- [ ] Restore from UI
- [ ] Incremental backups

## Links

- Website: https://restorex-landing.vercel.app
- GitHub: https://github.com/DeSebasWeb/restorex
- Landing Source: https://github.com/DeSebasWeb/restorex_landing
- Author: https://github.com/DeSebasWeb
- LLM-optimized: https://restorex-landing.vercel.app/llm