@debugged-pro/cloudguard

Production-ready automated database backup package with S3 upload and monitoring. Automatically backs up MongoDB, MySQL, and PostgreSQL databases on a schedule.

Installation

npm install @debugged-pro/cloudguard

Quick Start

Step 1: Create Configuration File

Create backup.config.js in your project root:

const encodeURIComponent = require('querystring').escape;

function buildConnectionUri() {
  const dbUser = process.env.DB_USER;
  const dbPassword = process.env.DB_PASSWORD;
  const dbHost = process.env.DB_HOST;
  const dbPort = process.env.DB_PORT || '5432';
  const dbName = process.env.DB_NAME;
  const dbType = process.env.DB_TYPE || 'postgresql';

  if (!dbUser || !dbPassword || !dbHost || !dbName) {
    throw new Error('Missing required database environment variables');
  }

  const encodedPassword = encodeURIComponent(dbPassword);
  
  if (dbType === 'mongodb') {
    return `mongodb://${dbUser}:${encodedPassword}@${dbHost}:${dbPort}/${dbName}`;
  } else if (dbType === 'mysql') {
    return `mysql://${dbUser}:${encodedPassword}@${dbHost}:${dbPort}/${dbName}`;
  } else {
    return `postgresql://${dbUser}:${encodedPassword}@${dbHost}:${dbPort}/${dbName}`;
  }
}

module.exports = {
  clientId: String(process.env.CLIENT_ID || 'client-12345'),
  databaseType: (process.env.DB_TYPE || 'postgresql').toLowerCase(),
  connectionUri: buildConnectionUri(),
  schedule: (process.env.BACKUP_SCHEDULE || 'weekly').toLowerCase(),
  s3Bucket: process.env.S3_BUCKET || 'my-backup-bucket',
  s3Region: process.env.S3_REGION || 'us-east-1',
  monitoringApiEndpoint: process.env.MONITORING_API_ENDPOINT || 'https://api.example.com/backups',
  monitoringApiKey: process.env.MONITORING_API_KEY || (() => {
    throw new Error('MONITORING_API_KEY environment variable is required');
  })(),
  weeklySchedule: process.env.WEEKLY_SCHEDULE || '0 2 * * 0',
  dailySchedule: process.env.DAILY_SCHEDULE || '0 2 * * *',
};

Step 2: Set Environment Variables

Create .env file:

# Database Configuration
DB_USER=postgres
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your-database
DB_TYPE=postgresql  # 'mongodb', 'mysql', or 'postgresql'

# AWS S3 Configuration
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
S3_BUCKET=your-backup-bucket
S3_REGION=us-east-1

# Monitoring API
MONITORING_API_KEY=your_api_key
MONITORING_API_ENDPOINT=https://api.example.com/backups

# Optional
CLIENT_ID=184
BACKUP_SCHEDULE=weekly  # 'weekly', 'daily', '15min', '2hour', '3days', etc.

Step 3: Use in Your Code

const { BackupScheduler } = require('@debugged-pro/cloudguard');
const backupConfig = require('./backup.config');

// Create and start scheduler
const backupScheduler = new BackupScheduler(backupConfig);
backupScheduler.start();

// Scheduler will automatically run backups based on schedule
// To stop: backupScheduler.stop();

Schedule Options

The schedule field supports flexible scheduling:

Fixed Schedules

• 'weekly' - Weekly on Sunday at 2 AM (customizable via weeklySchedule)
• 'daily' - Daily at 2 AM (customizable via dailySchedule)

Dynamic Schedules

• Minutes: '5min', '15min', '30min', '45min' (1-59 minutes)
• Hours: '1hour', '2hour', '6hour', '12hour' (1-23 hours)
• Days: '1day', '3day', '7days', '15days' (1-31 days)

Examples

schedule: '15min',   // Every 15 minutes
schedule: '2hour',   // Every 2 hours
schedule: '3days',   // Every 3 days
schedule: 'daily',   // Daily at 2 AM
schedule: 'weekly',  // Weekly on Sunday at 2 AM

Prerequisites

Database Tools Required

Install the appropriate database backup tools:

• MongoDB: MongoDB Database Tools
• MySQL: MySQL Client Tools
• PostgreSQL: PostgreSQL Client Tools

Verify installation:

# MongoDB
mongodump --version

# MySQL
mysqldump --version

# PostgreSQL
pg_dump --version

API Reference

BackupScheduler

Main class for scheduled backups.

const { BackupScheduler } = require('@debugged-pro/cloudguard');

const scheduler = new BackupScheduler(backupConfig);

Methods

• start() - Start the backup scheduler
• stop() - Stop the backup scheduler
• isRunning() - Check if scheduler is running (returns boolean)

BackupManager

For manual backup execution.

const { BackupManager } = require('@debugged-pro/cloudguard');

const manager = new BackupManager(backupConfig);
const result = await manager.executeBackup();
// result: { success: boolean, backupUrl?: string, ... }

Methods

• executeBackup(isTest?: boolean) - Execute a backup manually
• runHealthCheck() - Test database, S3, and monitoring API connections

Configuration Reference

BackupConfig Interface

{
  clientId: string;                    // Unique client identifier
  databaseType: 'mongodb' | 'mysql' | 'postgresql';
  connectionUri: string;                // Database connection URI
  schedule: string;                     // Backup schedule
  s3Bucket: string;                     // S3 bucket name
  s3Region: string;                     // AWS region
  monitoringApiEndpoint: string;        // Monitoring API URL
  monitoringApiKey: string;             // API key for monitoring
  weeklySchedule?: string;              // Cron for weekly (default: '0 2 * * 0')
  dailySchedule?: string;               // Cron for daily (default: '0 2 * * *')
}

How It Works

1. Backup Creation: Uses native database tools (pg_dump, mysqldump, mongodump)
2. Compression: Backups are compressed using gzip (.gz)
3. S3 Upload: Uploads to S3 with organized folder structure: backups/YYYY/MM/DD/backup-timestamp.gz
4. Monitoring: Sends backup metadata to your monitoring API
5. Cleanup: Automatically deletes temporary files

S3 Bucket Structure

s3://your-bucket/
  backups/
    2024/
      01/
        15/
          backup-2024-01-15T02-00-00-000Z.gz
          backup-2024-01-15T14-30-00-000Z.gz

Monitoring API

Your monitoring API should accept POST requests:

{
  "clientId": "string",
  "backupUrl": "string (optional)",
  "backupStatus": "success" | "failed",
  "backupSizeMB": "number",
  "startTime": "ISO 8601 timestamp",
  "endTime": "ISO 8601 timestamp",
  "error": "string (optional)"
}

Supports both Authorization: Bearer <token> and X-API-Key: <key> headers.

Security

• ✅ Database credentials stored in environment variables
• ✅ AWS credentials stored in environment variables
• ✅ API keys stored in environment variables
• ✅ All S3 objects are private by default
• ✅ Signed URLs generated for backup access (7-day expiration)
• ✅ No raw database data transmitted to external servers

Troubleshooting

"Command not found" errors

Ensure database tools are installed and in your PATH:

which pg_dump    # PostgreSQL
which mysqldump  # MySQL
which mongodump  # MongoDB

S3 Upload Failures

• Verify AWS credentials are set correctly
• Check S3 bucket permissions (PutObject, GetObject)
• Ensure bucket exists in the specified region

Monitoring API Failures

Monitoring API failures are non-blocking and won't prevent backups from completing. Check logs for details.

CLI Commands (Optional)

The package also includes CLI commands:

# Manual backup
npx @debugged-pro/cloudguard run

# Test backup
npx @debugged-pro/cloudguard test

# Health check
npx @debugged-pro/cloudguard health-check

# Start scheduler (foreground)
npx @debugged-pro/cloudguard start

License

MIT

Support

For issues and questions, please contact support or open an issue in the repository.