pg-r2-backup 1.0.4__tar.gz

pg_r2_backup-1.0.4/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: pg-r2-backup
+Version: 1.0.4
+Summary: PostgreSQL backup tool for Cloudflare R2 (S3 Compatuble)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3
+Requires-Dist: python-dotenv
+Requires-Dist: schedule
+Requires-Dist: py7zr
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.12-blue)
+![Storage](https://img.shields.io/badge/storage-S3--compatible-orange)
+![Database](https://img.shields.io/badge/database-PostgreSQL-336791)
+![Deploy](https://img.shields.io/badge/deploy-Railway-purple)
+![Docker](https://img.shields.io/badge/docker-supported-blue)
+
+# Postgres-to-R2 Backup (S3-Compatible)
+
+A lightweight automation service that creates scheduled PostgreSQL backups and securely uploads them to **S3-compatible object storage**
+such as **Cloudflare R2, AWS S3, Wasabi, Backblaze B2, or MinIO**.  
+Designed specifically as a **Railway deployment template**, with built-in support for Docker and cron scheduling.
+
+---
+
+## ✨ Features
+
+- 📦 **Automated Backups** — scheduled daily or hourly PostgreSQL backups  
+- 🔐 **Optional Encryption** — gzip compression or 7z encryption with password  
+- ☁️ **Cloudflare R2 Integration** — seamless S3-compatible storage support
+- 🧹 **Retention Policy** — automatically delete old backups  
+- 🔗 **Flexible Database URLs** — supports private and public PostgreSQL connection URLs
+- ⚡ **Optimized Performance** — parallel pg_dump and multipart S3 uploads
+- 🐳 **Docker Ready** — portable, lightweight container  
+- 🚀 **Railway Template First** — no fork required for normal usage  
+- 🪣 **S3-Compatible Storage** — works with R2, AWS S3, Wasabi, B2, MinIO
+
+---
+
+## 🚀 Deployment on Railway 
+
+1. Click the **Deploy on Railway** button below  
+2. Railway will create a new project using the latest version of this repository  
+3. Add the required environment variables in the Railway dashboard  
+4. (Optional) Configure a cron job for your desired backup schedule  
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/postgres-to-r2-backup?referralCode=nIQTyp&utm_medium=integration&utm_source=template&utm_campaign=generic)
+
+---
+
+## 🔧 Environment Variables (S3-Compatible)
+
+```env
+DATABASE_URL=           # PostgreSQL database URL (private)
+DATABASE_PUBLIC_URL=    # Public PostgreSQL URL (optional)
+USE_PUBLIC_URL=false    # Set true to use DATABASE_PUBLIC_URL
+
+DUMP_FORMAT=dump        # sql | plain | dump | custom | tar
+FILENAME_PREFIX=backup  # Backup filename prefix
+MAX_BACKUPS=7           # Number of backups to retain
+
+R2_ENDPOINT=            # S3 endpoint URL
+R2_BUCKET_NAME=         # Bucket name
+R2_ACCESS_KEY=          # Access key
+R2_SECRET_KEY=          # Secret key
+S3_REGION=us-east-1     # Required for AWS S3 (ignored by R2/MinIO)
+
+BACKUP_PASSWORD=        # Optional: enables 7z encryption
+BACKUP_TIME=00:00       # Daily backup time (UTC, HH:MM)
+```
+
+> Variable names use `R2_*` for historical reasons, but **any S3-compatible provider** can be used by changing the endpoint and credentials.
+> For AWS S3 users: ensure `S3_REGION` matches your bucket’s region.
+
+---
+
+## ☁️ Supported S3-Compatible Providers
+
+This project uses the **standard AWS S3 API via boto3**, and works with:
+
+- Cloudflare R2 (recommended)
+- AWS S3
+- Wasabi
+- Backblaze B2 (S3 API)
+- MinIO (self-hosted)
+
+### Example Endpoints
+
+| Provider | Endpoint Example |
+|--------|------------------|
+| Cloudflare R2 | `https://<accountid>.r2.cloudflarestorage.com` |
+| AWS S3 | `https://s3.amazonaws.com` |
+| Wasabi | `https://s3.wasabisys.com` |
+| Backblaze B2 | `https://s3.us-west-004.backblazeb2.com` |
+| MinIO | `http://localhost:9000` |
+
+---
+
+## ⏰ Railway Cron Jobs
+
+You can configure the backup schedule using **Railway Cron Jobs**:
+
+1. Open your Railway project  
+2. Go to **Deployments → Cron**  
+3. Add a cron job targeting this service  
+
+### Common Cron Expressions
+
+| Schedule | Cron Expression | Description |
+|--------|----------------|------------|
+| Hourly | `0 * * * *` | Every hour |
+| Daily | `0 0 * * *` | Once per day (UTC midnight) |
+| Twice Daily | `0 */12 * * *` | Every 12 hours |
+| Weekly | `0 0 * * 0` | Every Sunday |
+| Monthly | `0 0 1 * *` | First day of the month |
+
+**Tips**
+- All cron times are **UTC**
+- Use https://crontab.guru to validate expressions
+- Adjust `MAX_BACKUPS` to match your schedule
+
+> If you use Railway Cron Jobs, the service will start once per execution.
+> In this case, the internal scheduler is ignored after startup.
+
+---
+
+## 🖥️ Running Locally or on Other Platforms
+
+It can run on **any platform** that supports:
+- Python 3.9+
+- `pg_dump` (PostgreSQL client tools)
+- Environment variables
+- Long-running background processes or cron
+
+> Docker images use **Python 3.12** by default.  
+> Local execution supports **Python 3.9+**.
+
+### Supported Environments
+
+- Local machine (Linux / macOS / Windows*)
+- VPS (Netcup, Hetzner, DigitalOcean, etc.)
+- Docker containers
+- Other PaaS providers (Heroku, Fly.io, Render, etc.)
+
+> *Windows is supported when `pg_dump` is installed and available in PATH.*
+
+### Local Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`)
+- pip
+
+### Run Manually (Local)
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+### Run with Docker (Optional)
+
+Build and run the image locally:
+
+```bash
+docker build -t postgres-to-r2-backup .
+docker run --env-file .env postgres-to-r2-backup
+```
+
+> Ensure the container is allowed to run continuously when not using an external cron scheduler.
+
+> All scheduling uses **UTC** by default (e.g. Malaysia UTC+8 → set `BACKUP_TIME=16:00` for midnight).
+
+### Run from Prebuilt Docker Image
+
+If you downloaded a prebuilt Docker image archive (`.tar` or `.tar.gz`), you can run it without building locally:
+
+```bash
+# Extract the archive (if compressed)
+tar -xzf postgres-to-r2-backup_v1.0.4.tar.gz
+
+# Load the image into Docker
+docker load -i postgres-to-r2-backup_v1.0.4.tar
+
+# Run the container
+docker run --env-file .env postgres-to-r2-backup:v1.0.4
+```
+
+> Prebuilt images are architecture-specific (amd64 / arm64).
+
+---
+
+## 🧰 Using the CLI (Global Installation)
+
+This project can also be used as a standalone CLI tool, installable via pip, in addition to running as a Railway or Docker service.
+
+### Install via pip
+
+```bash
+pip install pg-r2-backup
+```
+
+### Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`) installed and available in PATH
+
+### Quick Start (CLI)
+
+```bash
+mkdir backups
+cd backups
+
+pg-r2-backup init      # creates .env from .env.example
+pg-r2-backup doctor    # checks environment and dependencies
+pg-r2-backup run       # runs a backup immediately
+```
+
+### CLI Commands
+
+```bash
+pg-r2-backup run            # Run backup immediately
+pg-r2-backup doctor         # Check environment & dependencies
+pg-r2-backup config show    # Show current configuration
+pg-r2-backup init           # Create .env from .env.example
+pg-r2-backup schedule       # Show scheduling examples
+pg-r2-backup --version
+```
+
+### Environment Variable Resolution (CLI)
+
+When running via the CLI, environment variables are resolved in the following order:
+
+1. A `.env` file in the current working directory (or parent directory)
+2. System environment variables
+
+This allows different folders to maintain separate backup configurations.
+
+### Scheduling Backups (CLI)
+
+The CLI does not run a background scheduler. Use your operating system or platform scheduler instead.
+
+**Linux / macOS (cron)**
+
+```bash
+0 0 * * * pg-r2-backup run
+```
+
+**Windows (Task Scheduler)**
+
+- Program: `pg-r2-backup`
+- Arguments: `run`
+- Start in: folder containing `.env` (working directory)
+
+**Railway / Docker**
+
+Use the platform's built-in scheduler (recommended).
+
+💡 **Tip**  
+Run `pg-r2-backup schedule` at any time to see scheduling examples.
+
+---
+
+## 🔐 Security
+
+- **Do not expose PostgreSQL directly to the public internet.**  
+  If your database is not on a private network, use a secure tunnel instead.
+
+- **Recommended: Cloudflare Tunnel**  
+  When using a public database URL, it is strongly recommended to connect via a secure tunnel such as **Cloudflare Tunnel** rather than opening database ports.
+
+- **Protect credentials**  
+  Store all secrets (database URLs, R2 keys, encryption passwords) using environment variables.  
+  Never commit `.env` files to version control.
+
+- **Encrypted backups (optional)**  
+  Set `BACKUP_PASSWORD` to enable encrypted backups using 7z before uploading to S3-compatible storage.
+
+- **Least privilege access**  
+  Use a PostgreSQL user with read-only access where possible, and restrict R2 credentials to the required bucket only.
+
+---
+
+## 🛠 Development & Contributions
+
+Fork this repository **only if you plan to**:
+
+- Modify the backup logic
+- Add features or integrations
+- Submit pull requests
+- Run locally for development
+
+---
+
+## ❓ FAQ
+
+**Why only DATABASE_URL?**  
+This matches how most modern platforms expose PostgreSQL credentials.  
+Support for separate DB variables may be added if there is demand.
+
+## 📜 License
+
+This project is open source under the **MIT License**.
+
+You are free to use, modify, and distribute it with attribution.

pg_r2_backup-1.0.4/README.md

@@ -0,0 +1,294 @@
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.12-blue)
+![Storage](https://img.shields.io/badge/storage-S3--compatible-orange)
+![Database](https://img.shields.io/badge/database-PostgreSQL-336791)
+![Deploy](https://img.shields.io/badge/deploy-Railway-purple)
+![Docker](https://img.shields.io/badge/docker-supported-blue)
+
+# Postgres-to-R2 Backup (S3-Compatible)
+
+A lightweight automation service that creates scheduled PostgreSQL backups and securely uploads them to **S3-compatible object storage**
+such as **Cloudflare R2, AWS S3, Wasabi, Backblaze B2, or MinIO**.  
+Designed specifically as a **Railway deployment template**, with built-in support for Docker and cron scheduling.
+
+---
+
+## ✨ Features
+
+- 📦 **Automated Backups** — scheduled daily or hourly PostgreSQL backups  
+- 🔐 **Optional Encryption** — gzip compression or 7z encryption with password  
+- ☁️ **Cloudflare R2 Integration** — seamless S3-compatible storage support
+- 🧹 **Retention Policy** — automatically delete old backups  
+- 🔗 **Flexible Database URLs** — supports private and public PostgreSQL connection URLs
+- ⚡ **Optimized Performance** — parallel pg_dump and multipart S3 uploads
+- 🐳 **Docker Ready** — portable, lightweight container  
+- 🚀 **Railway Template First** — no fork required for normal usage  
+- 🪣 **S3-Compatible Storage** — works with R2, AWS S3, Wasabi, B2, MinIO
+
+---
+
+## 🚀 Deployment on Railway 
+
+1. Click the **Deploy on Railway** button below  
+2. Railway will create a new project using the latest version of this repository  
+3. Add the required environment variables in the Railway dashboard  
+4. (Optional) Configure a cron job for your desired backup schedule  
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/postgres-to-r2-backup?referralCode=nIQTyp&utm_medium=integration&utm_source=template&utm_campaign=generic)
+
+---
+
+## 🔧 Environment Variables (S3-Compatible)
+
+```env
+DATABASE_URL=           # PostgreSQL database URL (private)
+DATABASE_PUBLIC_URL=    # Public PostgreSQL URL (optional)
+USE_PUBLIC_URL=false    # Set true to use DATABASE_PUBLIC_URL
+
+DUMP_FORMAT=dump        # sql | plain | dump | custom | tar
+FILENAME_PREFIX=backup  # Backup filename prefix
+MAX_BACKUPS=7           # Number of backups to retain
+
+R2_ENDPOINT=            # S3 endpoint URL
+R2_BUCKET_NAME=         # Bucket name
+R2_ACCESS_KEY=          # Access key
+R2_SECRET_KEY=          # Secret key
+S3_REGION=us-east-1     # Required for AWS S3 (ignored by R2/MinIO)
+
+BACKUP_PASSWORD=        # Optional: enables 7z encryption
+BACKUP_TIME=00:00       # Daily backup time (UTC, HH:MM)
+```
+
+> Variable names use `R2_*` for historical reasons, but **any S3-compatible provider** can be used by changing the endpoint and credentials.
+> For AWS S3 users: ensure `S3_REGION` matches your bucket’s region.
+
+---
+
+## ☁️ Supported S3-Compatible Providers
+
+This project uses the **standard AWS S3 API via boto3**, and works with:
+
+- Cloudflare R2 (recommended)
+- AWS S3
+- Wasabi
+- Backblaze B2 (S3 API)
+- MinIO (self-hosted)
+
+### Example Endpoints
+
+| Provider | Endpoint Example |
+|--------|------------------|
+| Cloudflare R2 | `https://<accountid>.r2.cloudflarestorage.com` |
+| AWS S3 | `https://s3.amazonaws.com` |
+| Wasabi | `https://s3.wasabisys.com` |
+| Backblaze B2 | `https://s3.us-west-004.backblazeb2.com` |
+| MinIO | `http://localhost:9000` |
+
+---
+
+## ⏰ Railway Cron Jobs
+
+You can configure the backup schedule using **Railway Cron Jobs**:
+
+1. Open your Railway project  
+2. Go to **Deployments → Cron**  
+3. Add a cron job targeting this service  
+
+### Common Cron Expressions
+
+| Schedule | Cron Expression | Description |
+|--------|----------------|------------|
+| Hourly | `0 * * * *` | Every hour |
+| Daily | `0 0 * * *` | Once per day (UTC midnight) |
+| Twice Daily | `0 */12 * * *` | Every 12 hours |
+| Weekly | `0 0 * * 0` | Every Sunday |
+| Monthly | `0 0 1 * *` | First day of the month |
+
+**Tips**
+- All cron times are **UTC**
+- Use https://crontab.guru to validate expressions
+- Adjust `MAX_BACKUPS` to match your schedule
+
+> If you use Railway Cron Jobs, the service will start once per execution.
+> In this case, the internal scheduler is ignored after startup.
+
+---
+
+## 🖥️ Running Locally or on Other Platforms
+
+It can run on **any platform** that supports:
+- Python 3.9+
+- `pg_dump` (PostgreSQL client tools)
+- Environment variables
+- Long-running background processes or cron
+
+> Docker images use **Python 3.12** by default.  
+> Local execution supports **Python 3.9+**.
+
+### Supported Environments
+
+- Local machine (Linux / macOS / Windows*)
+- VPS (Netcup, Hetzner, DigitalOcean, etc.)
+- Docker containers
+- Other PaaS providers (Heroku, Fly.io, Render, etc.)
+
+> *Windows is supported when `pg_dump` is installed and available in PATH.*
+
+### Local Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`)
+- pip
+
+### Run Manually (Local)
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+### Run with Docker (Optional)
+
+Build and run the image locally:
+
+```bash
+docker build -t postgres-to-r2-backup .
+docker run --env-file .env postgres-to-r2-backup
+```
+
+> Ensure the container is allowed to run continuously when not using an external cron scheduler.
+
+> All scheduling uses **UTC** by default (e.g. Malaysia UTC+8 → set `BACKUP_TIME=16:00` for midnight).
+
+### Run from Prebuilt Docker Image
+
+If you downloaded a prebuilt Docker image archive (`.tar` or `.tar.gz`), you can run it without building locally:
+
+```bash
+# Extract the archive (if compressed)
+tar -xzf postgres-to-r2-backup_v1.0.4.tar.gz
+
+# Load the image into Docker
+docker load -i postgres-to-r2-backup_v1.0.4.tar
+
+# Run the container
+docker run --env-file .env postgres-to-r2-backup:v1.0.4
+```
+
+> Prebuilt images are architecture-specific (amd64 / arm64).
+
+---
+
+## 🧰 Using the CLI (Global Installation)
+
+This project can also be used as a standalone CLI tool, installable via pip, in addition to running as a Railway or Docker service.
+
+### Install via pip
+
+```bash
+pip install pg-r2-backup
+```
+
+### Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`) installed and available in PATH
+
+### Quick Start (CLI)
+
+```bash
+mkdir backups
+cd backups
+
+pg-r2-backup init      # creates .env from .env.example
+pg-r2-backup doctor    # checks environment and dependencies
+pg-r2-backup run       # runs a backup immediately
+```
+
+### CLI Commands
+
+```bash
+pg-r2-backup run            # Run backup immediately
+pg-r2-backup doctor         # Check environment & dependencies
+pg-r2-backup config show    # Show current configuration
+pg-r2-backup init           # Create .env from .env.example
+pg-r2-backup schedule       # Show scheduling examples
+pg-r2-backup --version
+```
+
+### Environment Variable Resolution (CLI)
+
+When running via the CLI, environment variables are resolved in the following order:
+
+1. A `.env` file in the current working directory (or parent directory)
+2. System environment variables
+
+This allows different folders to maintain separate backup configurations.
+
+### Scheduling Backups (CLI)
+
+The CLI does not run a background scheduler. Use your operating system or platform scheduler instead.
+
+**Linux / macOS (cron)**
+
+```bash
+0 0 * * * pg-r2-backup run
+```
+
+**Windows (Task Scheduler)**
+
+- Program: `pg-r2-backup`
+- Arguments: `run`
+- Start in: folder containing `.env` (working directory)
+
+**Railway / Docker**
+
+Use the platform's built-in scheduler (recommended).
+
+💡 **Tip**  
+Run `pg-r2-backup schedule` at any time to see scheduling examples.
+
+---
+
+## 🔐 Security
+
+- **Do not expose PostgreSQL directly to the public internet.**  
+  If your database is not on a private network, use a secure tunnel instead.
+
+- **Recommended: Cloudflare Tunnel**  
+  When using a public database URL, it is strongly recommended to connect via a secure tunnel such as **Cloudflare Tunnel** rather than opening database ports.
+
+- **Protect credentials**  
+  Store all secrets (database URLs, R2 keys, encryption passwords) using environment variables.  
+  Never commit `.env` files to version control.
+
+- **Encrypted backups (optional)**  
+  Set `BACKUP_PASSWORD` to enable encrypted backups using 7z before uploading to S3-compatible storage.
+
+- **Least privilege access**  
+  Use a PostgreSQL user with read-only access where possible, and restrict R2 credentials to the required bucket only.
+
+---
+
+## 🛠 Development & Contributions
+
+Fork this repository **only if you plan to**:
+
+- Modify the backup logic
+- Add features or integrations
+- Submit pull requests
+- Run locally for development
+
+---
+
+## ❓ FAQ
+
+**Why only DATABASE_URL?**  
+This matches how most modern platforms expose PostgreSQL credentials.  
+Support for separate DB variables may be added if there is demand.
+
+## 📜 License
+
+This project is open source under the **MIT License**.
+
+You are free to use, modify, and distribute it with attribution.

pg_r2_backup-1.0.4/cli/cli.py

@@ -0,0 +1,166 @@
+import argparse
+import shutil
+import os
+import sys
+import textwrap
+import importlib.metadata
+
+from main import run_backup
+
+def get_version():
+    try:
+        return importlib.metadata.version("pg-r2-backup")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"
+
+
+def mask(value, show=4):
+    if not value:
+        return ""
+    if len(value) <= show:
+        return "*" * len(value)
+    return value[:show] + "*" * (len(value) - show)
+
+def doctor():
+    print("pg-r2-backup doctor\n")
+    
+    if shutil.which("pg_dump") is None:
+        print("[FAIL] pg_dump not found in PATH")
+    else:
+        print("[OK] pg_dump found")
+
+    required_envs = [
+        "DATABASE_URL",
+        "R2_ACCESS_KEY",
+        "R2_SECRET_KEY",
+        "R2_BUCKET_NAME",
+        "R2_ENDPOINT",
+    ]
+
+    missing = [e for e in required_envs if not os.environ.get(e)]
+
+    if missing:
+        print("\n[FAIL] Missing environment variables:")
+        for m in missing:
+            print(f"  - {m}")
+    else:
+        print("\n[OK] Required environment variables set")
+
+    use_public = os.environ.get("USE_PUBLIC_URL", "false").lower() == "true"
+    print(f"\nDatabase URL mode : {'public' if use_public else 'private'}")
+
+    if os.environ.get("BACKUP_PASSWORD"):
+        print("Compression      : 7z (encrypted)")
+    else:
+        print("Compression      : gzip")
+
+    print("\nDoctor check complete.")
+
+
+def config_show():
+    print("pg-r2-backup config\n")
+
+    config = {
+        "USE_PUBLIC_URL": os.environ.get("USE_PUBLIC_URL", "false"),
+        "DUMP_FORMAT": os.environ.get("DUMP_FORMAT", "dump"),
+        "FILENAME_PREFIX": os.environ.get("FILENAME_PREFIX", "backup"),
+        "MAX_BACKUPS": os.environ.get("MAX_BACKUPS", "7"),
+        "BACKUP_TIME": os.environ.get("BACKUP_TIME", "00:00"),
+        "R2_BUCKET_NAME": os.environ.get("R2_BUCKET_NAME", ""),
+        "R2_ENDPOINT": os.environ.get("R2_ENDPOINT", ""),
+        "R2_ACCESS_KEY": mask(os.environ.get("R2_ACCESS_KEY")),
+        "R2_SECRET_KEY": mask(os.environ.get("R2_SECRET_KEY")),
+    }
+
+    for k, v in config.items():
+        print(f"{k:<16} : {v}")
+
+
+def init_env():
+    if os.path.exists(".env"):
+        print("[ERROR] .env already exists")
+        return
+
+    example = ".env.example"
+    if not os.path.exists(example):
+        print("[ERROR] .env.example not found")
+        return
+
+    shutil.copy(example, ".env")
+    print("[SUCCESS] .env created from .env.example")
+    print("Edit the file before running backups.")
+
+
+def schedule_info():
+    print(textwrap.dedent("""
+    pg-r2-backup scheduling
+
+    Linux / macOS (cron):
+      0 0 * * * pg-r2-backup run
+
+    Windows (Task Scheduler):
+      Program : pg-r2-backup
+      Args    : run
+      Start in: folder containing .env (working directory)
+
+    Railway / Docker:
+      Use the platform scheduler
+    """).strip())
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="pg-r2-backup",
+        description="PostgreSQL backup tool for Cloudflare R2",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""
+            Examples:
+              pg-r2-backup doctor
+              pg-r2-backup run
+              pg-r2-backup config show
+              pg-r2-backup init
+              pg-r2-backup schedule
+        """)
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("run", help="Run backup immediately")
+    subparsers.add_parser("doctor", help="Check environment & dependencies")
+    subparsers.add_parser("schedule", help="Show scheduling examples")
+
+    config_parser = subparsers.add_parser("config", help="Show configuration")
+    config_sub = config_parser.add_subparsers(dest="subcommand")
+    config_sub.add_parser("show", help="Show current configuration")
+
+    subparsers.add_parser("init", help="Create .env from .env.example")
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        run_backup()
+
+    elif args.command == "doctor":
+        doctor()
+
+    elif args.command == "config" and args.subcommand == "show":
+        config_show()
+
+    elif args.command == "init":
+        init_env()
+
+    elif args.command == "schedule":
+        schedule_info()
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pg_r2_backup-1.0.4/main.py

@@ -0,0 +1,188 @@
+import os
+import subprocess
+import boto3
+from boto3.session import Config
+from datetime import datetime, timezone
+from boto3.s3.transfer import TransferConfig
+from dotenv import load_dotenv, find_dotenv
+import time
+import schedule
+import py7zr
+import shutil
+import gzip
+
+load_dotenv(find_dotenv(usecwd=True), override=True)
+
+## ENV
+
+DATABASE_URL = os.environ.get("DATABASE_URL")
+DATABASE_PUBLIC_URL = os.environ.get("DATABASE_PUBLIC_URL")
+R2_ACCESS_KEY = os.environ.get("R2_ACCESS_KEY")
+R2_SECRET_KEY = os.environ.get("R2_SECRET_KEY")
+R2_BUCKET_NAME = os.environ.get("R2_BUCKET_NAME")
+R2_ENDPOINT = os.environ.get("R2_ENDPOINT")
+MAX_BACKUPS = int(os.environ.get("MAX_BACKUPS", 7))
+BACKUP_PREFIX = os.environ.get("BACKUP_PREFIX", "")
+FILENAME_PREFIX = os.environ.get("FILENAME_PREFIX", "backup")
+DUMP_FORMAT = os.environ.get("DUMP_FORMAT", "dump")
+BACKUP_PASSWORD = os.environ.get("BACKUP_PASSWORD")
+USE_PUBLIC_URL = os.environ.get("USE_PUBLIC_URL", "false").lower() == "true"
+BACKUP_TIME = os.environ.get("BACKUP_TIME", "00:00")
+S3_REGION = os.environ.get("S3_REGION", "us-east-1")
+
+def log(msg):
+    print(msg, flush=True)
+
+## Validate BACKUP_TIME
+try:
+    hour, minute = BACKUP_TIME.split(":")
+    if not (0 <= int(hour) <= 23 and 0 <= int(minute) <= 59):
+        raise ValueError
+except ValueError:
+    log("[WARNING] Invalid BACKUP_TIME format. Using default: 00:00")
+    BACKUP_TIME = "00:00"
+
+def get_database_url():
+    if USE_PUBLIC_URL:
+        if not DATABASE_PUBLIC_URL:
+            raise ValueError("[ERROR] DATABASE_PUBLIC_URL not set but USE_PUBLIC_URL=true!")
+        return DATABASE_PUBLIC_URL
+
+    if not DATABASE_URL:
+        raise ValueError("[ERROR] DATABASE_URL not set!")
+    return DATABASE_URL
+
+def gzip_compress(src):
+    dst = src + ".gz"
+    with open(src, "rb") as f_in:
+        with gzip.open(dst, "wb") as f_out:
+            shutil.copyfileobj(f_in, f_out)
+    return dst
+
+def run_backup():
+    if shutil.which("pg_dump") is None:
+        log("[ERROR] pg_dump not found. Install postgresql-client.")
+        return
+
+    database_url = get_database_url()
+    log(f"[INFO] Using {'public' if USE_PUBLIC_URL else 'private'} database URL")
+
+    format_map = {
+        "sql": ("p", "sql"),
+        "plain": ("p", "sql"),
+        "dump": ("c", "dump"),
+        "custom": ("c", "dump"),
+        "tar": ("t", "tar")
+    }
+    pg_format, ext = format_map.get(DUMP_FORMAT.lower(), ("c", "dump"))
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    backup_file = f"{FILENAME_PREFIX}_{timestamp}.{ext}"
+
+    compressed_file = (
+        f"{backup_file}.7z" if BACKUP_PASSWORD else f"{backup_file}.gz"
+    )
+
+    compressed_file_r2 = f"{BACKUP_PREFIX}{compressed_file}"
+
+    ## Create backup
+    try:
+        log(f"[INFO] Creating backup {backup_file}")
+
+        dump_cmd = [
+            "pg_dump",
+            f"--dbname={database_url}",
+            "-F", pg_format,
+            "--no-owner",
+            "--no-acl",
+            "-f", backup_file
+        ]
+
+        subprocess.run(dump_cmd, check=True)
+
+        if BACKUP_PASSWORD:
+            log("[INFO] Encrypting backup with 7z...")
+            with py7zr.SevenZipFile(compressed_file, "w", password=BACKUP_PASSWORD) as archive:
+                archive.write(backup_file)
+            log("[SUCCESS] Backup encrypted successfully")
+        else:
+            log("[INFO] Compressing backup with gzip...")
+            gzip_compress(backup_file)
+            log("[SUCCESS] Backup compressed successfully")
+
+    except subprocess.CalledProcessError as e:
+        log(f"[ERROR] Backup creation failed: {e}")
+        return
+    finally:
+        if os.path.exists(backup_file):
+            os.remove(backup_file)
+
+    ## Upload to R2
+    if os.path.exists(compressed_file):
+        size = os.path.getsize(compressed_file)
+        log(f"[INFO] Final backup size: {size / 1024 / 1024:.2f} MB")
+
+    try:
+        client = boto3.client(
+            "s3",
+            endpoint_url=R2_ENDPOINT,
+            aws_access_key_id=R2_ACCESS_KEY,
+            aws_secret_access_key=R2_SECRET_KEY,
+            region_name=S3_REGION,
+            config=Config(
+                s3={"addressing_style": "path"}
+            )
+        )
+
+        config = TransferConfig(
+            multipart_threshold=8 * 1024 * 1024,
+            multipart_chunksize=8 * 1024 * 1024,
+            max_concurrency=4,
+            use_threads=True
+        )
+
+        client.upload_file(
+            compressed_file,
+            R2_BUCKET_NAME,
+            compressed_file_r2,
+            Config=config
+        )
+
+        log(f"[SUCCESS] Backup uploaded: {compressed_file_r2}")
+
+        objects = client.list_objects_v2(
+            Bucket=R2_BUCKET_NAME,
+            Prefix=BACKUP_PREFIX
+        )
+
+        if "Contents" in objects:
+            backups = sorted(
+                objects["Contents"],
+                key=lambda x: x["LastModified"],
+                reverse=True
+            )
+
+            for obj in backups[MAX_BACKUPS:]:
+                client.delete_object(
+                    Bucket=R2_BUCKET_NAME,
+                    Key=obj["Key"]
+                )
+                log(f"[INFO] Deleted old backup: {obj['Key']}")
+
+    except Exception as e:
+        log(f"[ERROR] R2 operation failed: {e}")
+    finally:
+        if os.path.exists(compressed_file):
+            os.remove(compressed_file)
+
+if __name__ == "__main__":
+    log("[INFO] Starting backup scheduler...")
+    log(f"[INFO] Scheduled backup time: {BACKUP_TIME} UTC")
+
+    schedule.every().day.at(BACKUP_TIME).do(run_backup)
+
+    run_backup()
+
+    while True:
+        schedule.run_pending()
+        time.sleep(60)

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: pg-r2-backup
+Version: 1.0.4
+Summary: PostgreSQL backup tool for Cloudflare R2 (S3 Compatuble)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3
+Requires-Dist: python-dotenv
+Requires-Dist: schedule
+Requires-Dist: py7zr
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.12-blue)
+![Storage](https://img.shields.io/badge/storage-S3--compatible-orange)
+![Database](https://img.shields.io/badge/database-PostgreSQL-336791)
+![Deploy](https://img.shields.io/badge/deploy-Railway-purple)
+![Docker](https://img.shields.io/badge/docker-supported-blue)
+
+# Postgres-to-R2 Backup (S3-Compatible)
+
+A lightweight automation service that creates scheduled PostgreSQL backups and securely uploads them to **S3-compatible object storage**
+such as **Cloudflare R2, AWS S3, Wasabi, Backblaze B2, or MinIO**.  
+Designed specifically as a **Railway deployment template**, with built-in support for Docker and cron scheduling.
+
+---
+
+## ✨ Features
+
+- 📦 **Automated Backups** — scheduled daily or hourly PostgreSQL backups  
+- 🔐 **Optional Encryption** — gzip compression or 7z encryption with password  
+- ☁️ **Cloudflare R2 Integration** — seamless S3-compatible storage support
+- 🧹 **Retention Policy** — automatically delete old backups  
+- 🔗 **Flexible Database URLs** — supports private and public PostgreSQL connection URLs
+- ⚡ **Optimized Performance** — parallel pg_dump and multipart S3 uploads
+- 🐳 **Docker Ready** — portable, lightweight container  
+- 🚀 **Railway Template First** — no fork required for normal usage  
+- 🪣 **S3-Compatible Storage** — works with R2, AWS S3, Wasabi, B2, MinIO
+
+---
+
+## 🚀 Deployment on Railway 
+
+1. Click the **Deploy on Railway** button below  
+2. Railway will create a new project using the latest version of this repository  
+3. Add the required environment variables in the Railway dashboard  
+4. (Optional) Configure a cron job for your desired backup schedule  
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/postgres-to-r2-backup?referralCode=nIQTyp&utm_medium=integration&utm_source=template&utm_campaign=generic)
+
+---
+
+## 🔧 Environment Variables (S3-Compatible)
+
+```env
+DATABASE_URL=           # PostgreSQL database URL (private)
+DATABASE_PUBLIC_URL=    # Public PostgreSQL URL (optional)
+USE_PUBLIC_URL=false    # Set true to use DATABASE_PUBLIC_URL
+
+DUMP_FORMAT=dump        # sql | plain | dump | custom | tar
+FILENAME_PREFIX=backup  # Backup filename prefix
+MAX_BACKUPS=7           # Number of backups to retain
+
+R2_ENDPOINT=            # S3 endpoint URL
+R2_BUCKET_NAME=         # Bucket name
+R2_ACCESS_KEY=          # Access key
+R2_SECRET_KEY=          # Secret key
+S3_REGION=us-east-1     # Required for AWS S3 (ignored by R2/MinIO)
+
+BACKUP_PASSWORD=        # Optional: enables 7z encryption
+BACKUP_TIME=00:00       # Daily backup time (UTC, HH:MM)
+```
+
+> Variable names use `R2_*` for historical reasons, but **any S3-compatible provider** can be used by changing the endpoint and credentials.
+> For AWS S3 users: ensure `S3_REGION` matches your bucket’s region.
+
+---
+
+## ☁️ Supported S3-Compatible Providers
+
+This project uses the **standard AWS S3 API via boto3**, and works with:
+
+- Cloudflare R2 (recommended)
+- AWS S3
+- Wasabi
+- Backblaze B2 (S3 API)
+- MinIO (self-hosted)
+
+### Example Endpoints
+
+| Provider | Endpoint Example |
+|--------|------------------|
+| Cloudflare R2 | `https://<accountid>.r2.cloudflarestorage.com` |
+| AWS S3 | `https://s3.amazonaws.com` |
+| Wasabi | `https://s3.wasabisys.com` |
+| Backblaze B2 | `https://s3.us-west-004.backblazeb2.com` |
+| MinIO | `http://localhost:9000` |
+
+---
+
+## ⏰ Railway Cron Jobs
+
+You can configure the backup schedule using **Railway Cron Jobs**:
+
+1. Open your Railway project  
+2. Go to **Deployments → Cron**  
+3. Add a cron job targeting this service  
+
+### Common Cron Expressions
+
+| Schedule | Cron Expression | Description |
+|--------|----------------|------------|
+| Hourly | `0 * * * *` | Every hour |
+| Daily | `0 0 * * *` | Once per day (UTC midnight) |
+| Twice Daily | `0 */12 * * *` | Every 12 hours |
+| Weekly | `0 0 * * 0` | Every Sunday |
+| Monthly | `0 0 1 * *` | First day of the month |
+
+**Tips**
+- All cron times are **UTC**
+- Use https://crontab.guru to validate expressions
+- Adjust `MAX_BACKUPS` to match your schedule
+
+> If you use Railway Cron Jobs, the service will start once per execution.
+> In this case, the internal scheduler is ignored after startup.
+
+---
+
+## 🖥️ Running Locally or on Other Platforms
+
+It can run on **any platform** that supports:
+- Python 3.9+
+- `pg_dump` (PostgreSQL client tools)
+- Environment variables
+- Long-running background processes or cron
+
+> Docker images use **Python 3.12** by default.  
+> Local execution supports **Python 3.9+**.
+
+### Supported Environments
+
+- Local machine (Linux / macOS / Windows*)
+- VPS (Netcup, Hetzner, DigitalOcean, etc.)
+- Docker containers
+- Other PaaS providers (Heroku, Fly.io, Render, etc.)
+
+> *Windows is supported when `pg_dump` is installed and available in PATH.*
+
+### Local Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`)
+- pip
+
+### Run Manually (Local)
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+### Run with Docker (Optional)
+
+Build and run the image locally:
+
+```bash
+docker build -t postgres-to-r2-backup .
+docker run --env-file .env postgres-to-r2-backup
+```
+
+> Ensure the container is allowed to run continuously when not using an external cron scheduler.
+
+> All scheduling uses **UTC** by default (e.g. Malaysia UTC+8 → set `BACKUP_TIME=16:00` for midnight).
+
+### Run from Prebuilt Docker Image
+
+If you downloaded a prebuilt Docker image archive (`.tar` or `.tar.gz`), you can run it without building locally:
+
+```bash
+# Extract the archive (if compressed)
+tar -xzf postgres-to-r2-backup_v1.0.4.tar.gz
+
+# Load the image into Docker
+docker load -i postgres-to-r2-backup_v1.0.4.tar
+
+# Run the container
+docker run --env-file .env postgres-to-r2-backup:v1.0.4
+```
+
+> Prebuilt images are architecture-specific (amd64 / arm64).
+
+---
+
+## 🧰 Using the CLI (Global Installation)
+
+This project can also be used as a standalone CLI tool, installable via pip, in addition to running as a Railway or Docker service.
+
+### Install via pip
+
+```bash
+pip install pg-r2-backup
+```
+
+### Requirements
+
+- Python 3.9+
+- PostgreSQL client tools (`pg_dump`) installed and available in PATH
+
+### Quick Start (CLI)
+
+```bash
+mkdir backups
+cd backups
+
+pg-r2-backup init      # creates .env from .env.example
+pg-r2-backup doctor    # checks environment and dependencies
+pg-r2-backup run       # runs a backup immediately
+```
+
+### CLI Commands
+
+```bash
+pg-r2-backup run            # Run backup immediately
+pg-r2-backup doctor         # Check environment & dependencies
+pg-r2-backup config show    # Show current configuration
+pg-r2-backup init           # Create .env from .env.example
+pg-r2-backup schedule       # Show scheduling examples
+pg-r2-backup --version
+```
+
+### Environment Variable Resolution (CLI)
+
+When running via the CLI, environment variables are resolved in the following order:
+
+1. A `.env` file in the current working directory (or parent directory)
+2. System environment variables
+
+This allows different folders to maintain separate backup configurations.
+
+### Scheduling Backups (CLI)
+
+The CLI does not run a background scheduler. Use your operating system or platform scheduler instead.
+
+**Linux / macOS (cron)**
+
+```bash
+0 0 * * * pg-r2-backup run
+```
+
+**Windows (Task Scheduler)**
+
+- Program: `pg-r2-backup`
+- Arguments: `run`
+- Start in: folder containing `.env` (working directory)
+
+**Railway / Docker**
+
+Use the platform's built-in scheduler (recommended).
+
+💡 **Tip**  
+Run `pg-r2-backup schedule` at any time to see scheduling examples.
+
+---
+
+## 🔐 Security
+
+- **Do not expose PostgreSQL directly to the public internet.**  
+  If your database is not on a private network, use a secure tunnel instead.
+
+- **Recommended: Cloudflare Tunnel**  
+  When using a public database URL, it is strongly recommended to connect via a secure tunnel such as **Cloudflare Tunnel** rather than opening database ports.
+
+- **Protect credentials**  
+  Store all secrets (database URLs, R2 keys, encryption passwords) using environment variables.  
+  Never commit `.env` files to version control.
+
+- **Encrypted backups (optional)**  
+  Set `BACKUP_PASSWORD` to enable encrypted backups using 7z before uploading to S3-compatible storage.
+
+- **Least privilege access**  
+  Use a PostgreSQL user with read-only access where possible, and restrict R2 credentials to the required bucket only.
+
+---
+
+## 🛠 Development & Contributions
+
+Fork this repository **only if you plan to**:
+
+- Modify the backup logic
+- Add features or integrations
+- Submit pull requests
+- Run locally for development
+
+---
+
+## ❓ FAQ
+
+**Why only DATABASE_URL?**  
+This matches how most modern platforms expose PostgreSQL credentials.  
+Support for separate DB variables may be added if there is demand.
+
+## 📜 License
+
+This project is open source under the **MIT License**.
+
+You are free to use, modify, and distribute it with attribution.

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+main.py
+pyproject.toml
+cli/__init__.py
+cli/cli.py
+pg_r2_backup.egg-info/PKG-INFO
+pg_r2_backup.egg-info/SOURCES.txt
+pg_r2_backup.egg-info/dependency_links.txt
+pg_r2_backup.egg-info/entry_points.txt
+pg_r2_backup.egg-info/requires.txt
+pg_r2_backup.egg-info/top_level.txt

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pg-r2-backup = cli.cli:main

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/requires.txt

@@ -0,0 +1,4 @@
+boto3
+python-dotenv
+schedule
+py7zr

pg_r2_backup-1.0.4/pg_r2_backup.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+cli
+main

pg_r2_backup-1.0.4/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pg-r2-backup"
+version = "1.0.4"
+description = "PostgreSQL backup tool for Cloudflare R2 (S3 Compatuble)"
+readme = "README.md"
+requires-python = ">=3.9"
+
+dependencies = [
+    "boto3",
+    "python-dotenv",
+    "schedule",
+    "py7zr"
+]
+
+[tool.setuptools]
+packages = ["cli"]
+py-modules = ["main"]
+
+[project.scripts]
+pg-r2-backup = "cli.cli:main"

pg_r2_backup-1.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+