universal-db-backup 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# universal-db-backup
+
+A universal database backup tool for Node.js that supports MongoDB, MySQL, and PostgreSQL using native dump utilities (`mongodump`, `mysqldump`, `pg_dump`).
+
+## Features
+
+- **Multi-database support**: MongoDB, MySQL, PostgreSQL
+- **Parameter-based configuration**: Simple object config for each database type
+- **Promise-based API**: Clean async/await support
+- **Optional ZIP compression**: Compress backups after creation
+- **Scheduling**: Cron-based recurring backups via `node-cron`
+- **CLI support**: Run backups from the command line
+
+## Prerequisites
+
+Install the appropriate dump utility for your database:
+
+- **MongoDB**: [mongodump](https://docs.mongodb.com/database-tools/mongodump/) (included with MongoDB tools)
+- **MySQL**: [mysqldump](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html) (included with MySQL client)
+- **PostgreSQL**: [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) (included with PostgreSQL)
+
+## Installation
+
+```bash
+npm install universal-db-backup
+```
+
+## API Usage
+
+### MongoDB
+
+```javascript
+const { backup } = require('universal-db-backup');
+
+backup({
+  dbType: 'mongodb',
+  uri: 'mongodb://localhost:27017/mydb',
+  output: './backup',
+  zip: true, // optional: compress to ZIP
+  gzip: true, // optional: use gzip for mongodump
+}).then((result) => {
+  console.log('Backup path:', result.path);
+  if (result.zipPath) console.log('ZIP path:', result.zipPath);
+}).catch(console.error);
+```
+
+### MySQL
+
+```javascript
+const { backup } = require('universal-db-backup');
+
+backup({
+  dbType: 'mysql',
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: '123',
+  database: 'mydb',
+  output: './backup',
+  zip: true, // optional
+}).then((result) => {
+  console.log('Backup path:', result.path);
+}).catch(console.error);
+```
+
+### PostgreSQL
+
+```javascript
+const { backup } = require('universal-db-backup');
+
+backup({
+  dbType: 'postgres',
+  host: 'localhost',
+  port: 5432,
+  user: 'postgres',
+  password: 'secret',
+  database: 'mydb',
+  output: './backup',
+  zip: true, // optional
+  format: 'plain', // 'plain' | 'custom' | 'directory' | 'tar'
+}).then((result) => {
+  console.log('Backup path:', result.path);
+}).catch(console.error);
+```
+
+### Scheduled Backups
+
+```javascript
+const { schedule } = require('universal-db-backup');
+
+const job = schedule(
+  {
+    dbType: 'mongodb',
+    uri: 'mongodb://localhost:27017/mydb',
+    output: './backup',
+    zip: true,
+  },
+  '0 2 * * *', // Every day at 2:00 AM
+  { zip: true }
+);
+
+// Stop scheduler when needed
+// job.stop();
+```
+
+### async/await
+
+```javascript
+const { backup } = require('universal-db-backup');
+
+async function runBackup() {
+  try {
+    const result = await backup({
+      dbType: 'mysql',
+      host: 'localhost',
+      user: 'root',
+      password: '123',
+      database: 'mydb',
+      output: './backup',
+    });
+    console.log('Success:', result.path);
+  } catch (err) {
+    console.error('Failed:', err.message);
+  }
+}
+
+runBackup();
+```
+
+## CLI Usage
+
+Install globally or use via `npx`:
+
+```bash
+npm install -g universal-db-backup
+```
+
+### One-time backup
+
+```bash
+# MongoDB
+universal-db-backup backup -t mongodb -u "mongodb://localhost:27017/mydb" -o ./backup
+
+# MySQL
+universal-db-backup backup -t mysql -H localhost -U root -p 123 -d mydb -o ./backup
+
+# PostgreSQL
+universal-db-backup backup -t postgres -H localhost -U postgres -p secret -d mydb -o ./backup
+
+# With ZIP compression
+universal-db-backup backup -t mongodb -u "mongodb://localhost:27017/mydb" -o ./backup -z
+```
+
+### Scheduled backup
+
+```bash
+# Daily at 2:00 AM
+universal-db-backup schedule -t mysql -H localhost -U root -p 123 -d mydb -o ./backup -c "0 2 * * *"
+
+# Every 6 hours
+universal-db-backup schedule -t mongodb -u "mongodb://localhost:27017/mydb" -o ./backup -c "0 */6 * * *"
+```
+
+### Short alias
+
+```bash
+udb-backup backup -t mysql -U root -d mydb -o ./backup
+```
+
+### CLI Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| --type | -t | Database type: mongodb, mysql, postgres |
+| --output | -o | Output directory |
+| --uri | -u | MongoDB connection URI |
+| --host | -H | Database host (default: localhost) |
+| --port | -P | Database port |
+| --user | -U | Database user |
+| --password | -p | Database password |
+| --database | -d | Database name |
+| --zip | -z | Compress backup to ZIP |
+| --cron | -c | Cron expression (schedule command only) |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * universal-db-backup CLI
+ * Usage: universal-db-backup [options] or udb-backup [options]
+ */
+
+const path = require('path');
+const { program } = require('commander');
+const { backup, schedule, logger } = require('../src/index');
+
+const pkg = require(path.join(__dirname, '../package.json'));
+
+program
+  .name('universal-db-backup')
+  .description('Universal database backup tool for MongoDB, MySQL, and PostgreSQL')
+  .version(pkg.version);
+
+program
+  .command('backup')
+  .description('Run a one-time backup')
+  .requiredOption('-t, --type <dbType>', 'Database type: mongodb, mysql, postgres')
+  .requiredOption('-o, --output <path>', 'Output directory for backup')
+  .option('-u, --uri <uri>', 'MongoDB connection URI (for mongodb)')
+  .option('-H, --host <host>', 'Database host (for mysql/postgres)', 'localhost')
+  .option('-P, --port <port>', 'Database port', '')
+  .option('-U, --user <user>', 'Database user (for mysql/postgres)')
+  .option('-p, --password <password>', 'Database password')
+  .option('-d, --database <name>', 'Database name (for mysql/postgres)')
+  .option('-z, --zip', 'Compress backup to ZIP after completion')
+  .option('--gzip', 'Use gzip for MongoDB dump')
+  .action(async (options) => {
+    try {
+      const config = buildConfig(options);
+      const result = await backup(config);
+      logger.success(`Backup completed: ${result.path}`);
+      if (result.zipPath) {
+        logger.success(`Compressed: ${result.zipPath}`);
+      }
+      process.exit(0);
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('schedule')
+  .description('Schedule recurring backups with cron')
+  .requiredOption('-t, --type <dbType>', 'Database type: mongodb, mysql, postgres')
+  .requiredOption('-o, --output <path>', 'Output directory for backup')
+  .requiredOption('-c, --cron <expression>', 'Cron expression (e.g., "0 2 * * *" for daily at 2 AM)')
+  .option('-u, --uri <uri>', 'MongoDB connection URI (for mongodb)')
+  .option('-H, --host <host>', 'Database host (for mysql/postgres)', 'localhost')
+  .option('-P, --port <port>', 'Database port', '')
+  .option('-U, --user <user>', 'Database user (for mysql/postgres)')
+  .option('-p, --password <password>', 'Database password')
+  .option('-d, --database <name>', 'Database name (for mysql/postgres)')
+  .option('-z, --zip', 'Compress backup to ZIP after completion')
+  .action(async (options) => {
+    try {
+      const config = buildConfig(options);
+      const job = schedule(config, options.cron, { zip: options.zip });
+      logger.success(`Scheduled backup: ${options.cron} (${config.dbType})`);
+      logger.info('Press Ctrl+C to stop scheduler');
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Build backup config from CLI options
+ */
+function buildConfig(options) {
+  const config = {
+    dbType: options.type,
+    output: options.output,
+    zip: options.zip,
+  };
+
+  if (options.type === 'mongodb') {
+    if (!options.uri) {
+      throw new Error('MongoDB requires --uri');
+    }
+    config.uri = options.uri;
+    if (options.gzip) config.gzip = true;
+  } else if (options.type === 'mysql' || options.type === 'postgres') {
+    config.host = options.host;
+    config.user = options.user;
+    config.password = options.password;
+    config.database = options.database;
+    if (options.port) {
+      config.port = parseInt(options.port, 10);
+    }
+    if (!config.user || !config.database) {
+      throw new Error('MySQL/Postgres requires --user and --database');
+    }
+  }
+
+  return config;
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "universal-db-backup",
+  "version": "1.0.0",
+  "description": "Universal database backup tool supporting MongoDB, MySQL, and PostgreSQL",
+  "main": "src/index.js",
+  "bin": {
+    "universal-db-backup": "bin/cli.js",
+    "udb-backup": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "database",
+    "backup",
+    "mongodb",
+    "mysql",
+    "postgresql",
+    "mongodump",
+    "mysqldump",
+    "pg_dump"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-cron": "^3.0.3",
+    "archiver": "^7.0.1",
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/"
+  ]
+}

package/src/backup/mongodb.js

@@ -0,0 +1,62 @@
+/**
+ * MongoDB backup handler using mongodump
+ * Requires mongodump to be installed and in PATH
+ */
+
+const { exec } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { promisify } = require('util');
+const logger = require('../utils/logger');
+
+const execAsync = promisify(exec);
+
+/**
+ * Execute MongoDB backup using mongodump
+ * @param {Object} config - Backup configuration
+ * @param {string} config.uri - MongoDB connection URI (e.g., mongodb://localhost:27017/mydb)
+ * @param {string} config.output - Output directory for backup
+ * @param {boolean} [config.gzip] - Use gzip compression for dump
+ * @returns {Promise<string>} - Path to backup directory
+ */
+async function backupMongoDB(config) {
+  const { uri, output, gzip = false } = config;
+
+  if (!uri) {
+    throw new Error('MongoDB backup requires "uri" in config');
+  }
+
+  if (!output) {
+    throw new Error('Backup requires "output" directory in config');
+  }
+
+  // Create output directory if it doesn't exist
+  const outputPath = path.resolve(output);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(outputPath, `mongodb-backup-${timestamp}`);
+
+  if (!fs.existsSync(outputPath)) {
+    fs.mkdirSync(outputPath, { recursive: true });
+  }
+
+  let command = `mongodump --uri="${uri}" --out="${backupDir}"`;
+  if (gzip) {
+    command += ' --gzip';
+  }
+
+  logger.info(`Starting MongoDB backup to ${backupDir}`);
+  try {
+    const { stdout, stderr } = await execAsync(command);
+    if (stdout) logger.info(stdout.trim());
+    if (stderr) logger.warn(stderr.trim());
+    logger.success(`MongoDB backup completed: ${backupDir}`);
+    return backupDir;
+  } catch (err) {
+    logger.error(`MongoDB backup failed: ${err.message}`);
+    throw new Error(`MongoDB backup failed: ${err.message}. Ensure mongodump is installed.`);
+  }
+}
+
+module.exports = {
+  backupMongoDB,
+};

package/src/backup/mysql.js

@@ -0,0 +1,92 @@
+/**
+ * MySQL backup handler using mysqldump
+ * Requires mysqldump to be installed and in PATH
+ */
+
+const { exec } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { promisify } = require('util');
+const logger = require('../utils/logger');
+
+const execAsync = promisify(exec);
+
+/**
+ * Build mysqldump command with proper escaping
+ * @param {Object} config - Backup configuration
+ * @returns {string} - Backup file path
+ */
+function buildMysqldumpConfig(config) {
+  const {
+    host = 'localhost',
+    port = 3306,
+    user,
+    password,
+    database,
+    output,
+  } = config;
+
+  if (!user || !database) {
+    throw new Error('MySQL backup requires "user" and "database" in config');
+  }
+
+  if (!output) {
+    throw new Error('Backup requires "output" directory in config');
+  }
+
+  const outputPath = path.resolve(output);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupFile = path.join(outputPath, `mysql-${database}-${timestamp}.sql`);
+
+  if (!fs.existsSync(outputPath)) {
+    fs.mkdirSync(outputPath, { recursive: true });
+  }
+
+  // Use --result-file for cross-platform support (no shell redirect needed)
+  const args = [
+    '-h', host,
+    '-P', String(port),
+    '-u', user,
+    '--single-transaction',
+    '--routines',
+    '--triggers',
+    '--result-file', backupFile,
+    database,
+  ];
+  const command = 'mysqldump ' + args.map((a) => `"${String(a).replace(/"/g, '\\"')}"`).join(' ');
+
+  return { command, backupFile };
+}
+
+/**
+ * Execute MySQL backup using mysqldump
+ * @param {Object} config - Backup configuration
+ * @param {string} config.host - MySQL host (default: localhost)
+ * @param {number} config.port - MySQL port (default: 3306)
+ * @param {string} config.user - MySQL user
+ * @param {string} [config.password] - MySQL password
+ * @param {string} config.database - Database name
+ * @param {string} config.output - Output directory for backup
+ * @returns {Promise<string>} - Path to backup file
+ */
+async function backupMySQL(config) {
+  const { command, backupFile } = buildMysqldumpConfig(config);
+
+  logger.info(`Starting MySQL backup to ${backupFile}`);
+  try {
+    await execAsync(command, {
+      shell: true,
+      env: { ...process.env, MYSQL_PWD: config.password || '' },
+    });
+    logger.success(`MySQL backup completed: ${backupFile}`);
+    return backupFile;
+  } catch (err) {
+    logger.error(`MySQL backup failed: ${err.message}`);
+    throw new Error(`MySQL backup failed: ${err.message}. Ensure mysqldump is installed.`);
+  }
+}
+
+module.exports = {
+  backupMySQL,
+  buildMysqldumpConfig,
+};

package/src/backup/postgres.js

@@ -0,0 +1,88 @@
+/**
+ * PostgreSQL backup handler using pg_dump
+ * Requires pg_dump to be installed and in PATH
+ */
+
+const { exec } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { promisify } = require('util');
+const logger = require('../utils/logger');
+
+const execAsync = promisify(exec);
+
+/**
+ * Execute PostgreSQL backup using pg_dump
+ * @param {Object} config - Backup configuration
+ * @param {string} [config.host] - PostgreSQL host (default: localhost)
+ * @param {number} [config.port] - PostgreSQL port (default: 5432)
+ * @param {string} [config.user] - PostgreSQL user
+ * @param {string} [config.password] - PostgreSQL password (set via PGPASSWORD env)
+ * @param {string} config.database - Database name
+ * @param {string} config.output - Output directory for backup
+ * @param {string} [config.format] - pg_dump format: 'plain' | 'custom' | 'directory' | 'tar' (default: plain)
+ * @returns {Promise<string>} - Path to backup file
+ */
+async function backupPostgres(config) {
+  const {
+    host = 'localhost',
+    port = 5432,
+    user,
+    password,
+    database,
+    output,
+    format = 'plain',
+  } = config;
+
+  if (!database) {
+    throw new Error('PostgreSQL backup requires "database" in config');
+  }
+
+  if (!output) {
+    throw new Error('Backup requires "output" directory in config');
+  }
+
+  const outputPath = path.resolve(output);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const extension = format === 'plain' ? 'sql' : format === 'custom' ? 'dump' : format;
+  const backupFile = path.join(outputPath, `postgres-${database}-${timestamp}.${extension}`);
+
+  if (!fs.existsSync(outputPath)) {
+    fs.mkdirSync(outputPath, { recursive: true });
+  }
+
+  const args = [
+    '-h', host,
+    '-p', port,
+    '-U', user || process.env.USER || 'postgres',
+    '-d', database,
+    '-f', backupFile,
+  ];
+
+  if (format !== 'plain') {
+    args.push('-F', format === 'custom' ? 'c' : format === 'directory' ? 'd' : 't');
+  }
+
+  const command = 'pg_dump ' + args.map((a) => `"${String(a).replace(/"/g, '\\"')}"`).join(' ');
+  const env = { ...process.env };
+  if (password) {
+    env.PGPASSWORD = password;
+  }
+
+  logger.info(`Starting PostgreSQL backup to ${backupFile}`);
+  try {
+    await execAsync(command, {
+      shell: true,
+      env,
+    });
+    logger.success(`PostgreSQL backup completed: ${backupFile}`);
+    return backupFile;
+  } catch (err) {
+    logger.error(`PostgreSQL backup failed: ${err.message}`);
+    throw new Error(`PostgreSQL backup failed: ${err.message}. Ensure pg_dump is installed.`);
+  }
+}
+
+module.exports = {
+  backupPostgres,
+};

package/src/index.js

@@ -0,0 +1,101 @@
+/**
+ * universal-db-backup
+ * Main controller - detects dbType and routes to appropriate backup handler
+ */
+
+const path = require('path');
+const { backupMongoDB } = require('./backup/mongodb');
+const { backupMySQL } = require('./backup/mysql');
+const { backupPostgres } = require('./backup/postgres');
+const { compressDirectory } = require('./utils/zip');
+const cron = require('node-cron');
+const logger = require('./utils/logger');
+
+/** Supported database types */
+const SUPPORTED_DB_TYPES = ['mongodb', 'mysql', 'postgres', 'postgresql'];
+
+/**
+ * Schedule a backup using cron expression
+ * @param {Object} config - Backup configuration (same as backup())
+ * @param {string} cronExpression - Cron expression (e.g., '0 2 * * *' for daily at 2 AM)
+ * @param {Object} [options] - Additional options
+ * @param {boolean} [options.zip] - Compress backup after completion
+ * @returns {Object} - Cron job object with .stop() method
+ */
+function schedule(config, cronExpression, options = {}) {
+  if (!cron.validate(cronExpression)) {
+    throw new Error(`Invalid cron expression: ${cronExpression}`);
+  }
+
+  const backupConfig = { ...config, zip: options.zip || config.zip || false };
+  const job = cron.schedule(cronExpression, async () => {
+    try {
+      logger.info(`Scheduled backup started (${config.dbType})`);
+      const result = await backup(backupConfig);
+      logger.success(`Scheduled backup completed: ${result.path}`);
+    } catch (err) {
+      logger.error(`Scheduled backup failed: ${err.message}`);
+    }
+  });
+
+  return job;
+}
+
+/**
+ * Execute database backup based on configuration
+ * @param {Object} config - Backup configuration
+ * @param {string} config.dbType - Database type: 'mongodb' | 'mysql' | 'postgres' | 'postgresql'
+ * @param {string} config.output - Output directory for backup
+ * @param {boolean} [config.zip] - Compress backup to ZIP after completion (default: false)
+ * @param {...*} config - Additional db-specific config (uri for MongoDB; host, user, password, database for MySQL/Postgres)
+ * @returns {Promise<Object>} - { path: string, zipPath?: string }
+ */
+async function backup(config) {
+  const { dbType, output, zip: shouldZip = false } = config;
+
+  if (!dbType) {
+    throw new Error('Backup requires "dbType" in config (mongodb | mysql | postgres)');
+  }
+
+  const normalizedType = dbType.toLowerCase();
+  if (!SUPPORTED_DB_TYPES.includes(normalizedType)) {
+    throw new Error(
+      `Unsupported dbType: ${dbType}. Supported: ${SUPPORTED_DB_TYPES.join(', ')}`
+    );
+  }
+
+  let backupPath;
+
+  switch (normalizedType) {
+    case 'mongodb':
+      backupPath = await backupMongoDB(config);
+      break;
+    case 'mysql':
+      backupPath = await backupMySQL(config);
+      break;
+    case 'postgres':
+    case 'postgresql':
+      backupPath = await backupPostgres(config);
+      break;
+    default:
+      throw new Error(`No handler for dbType: ${dbType}`);
+  }
+
+  const result = { path: backupPath };
+
+  if (shouldZip) {
+    logger.info('Compressing backup to ZIP...');
+    const zipPath = await compressDirectory(backupPath);
+    result.zipPath = zipPath;
+    logger.success(`Backup compressed: ${zipPath}`);
+  }
+
+  return result;
+}
+
+module.exports = {
+  backup,
+  schedule,
+  SUPPORTED_DB_TYPES,
+  logger,
+};

package/src/utils/logger.js

@@ -0,0 +1,59 @@
+/**
+ * Simple logger utility for consistent console output
+ * Supports log levels: info, success, warn, error
+ */
+
+const LOG_LEVELS = {
+  info: '\x1b[36m',    // Cyan
+  success: '\x1b[32m', // Green
+  warn: '\x1b[33m',    // Yellow
+  error: '\x1b[31m',   // Red
+};
+const RESET = '\x1b[0m';
+
+/**
+ * Format and log a message with optional level
+ * @param {string} message - Message to log
+ * @param {string} level - Log level (info|success|warn|error)
+ */
+function log(message, level = 'info') {
+  const color = LOG_LEVELS[level] || LOG_LEVELS.info;
+  const prefix = level === 'success' ? '✓' : level === 'error' ? '✗' : level === 'warn' ? '!' : '→';
+  console.log(`${color}${prefix} ${message}${RESET}`);
+}
+
+/**
+ * Log info message
+ */
+function info(message) {
+  log(message, 'info');
+}
+
+/**
+ * Log success message
+ */
+function success(message) {
+  log(message, 'success');
+}
+
+/**
+ * Log warning message
+ */
+function warn(message) {
+  log(message, 'warn');
+}
+
+/**
+ * Log error message
+ */
+function error(message) {
+  log(message, 'error');
+}
+
+module.exports = {
+  log,
+  info,
+  success,
+  warn,
+  error,
+};

package/src/utils/zip.js

@@ -0,0 +1,47 @@
+/**
+ * ZIP compression utility for backup folders
+ * Uses archiver to create compressed archives
+ */
+
+const path = require('path');
+const fs = require('fs');
+const archiver = require('archiver');
+
+/**
+ * Compress a directory into a ZIP file
+ * @param {string} sourceDir - Path to directory to compress
+ * @param {string} outputPath - Path for output ZIP file (optional, defaults to sourceDir.zip)
+ * @returns {Promise<string>} - Resolves with path to created ZIP file
+ */
+function compressDirectory(sourceDir, outputPath = null) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(sourceDir)) {
+      reject(new Error(`Source directory does not exist: ${sourceDir}`));
+      return;
+    }
+
+    const dirName = path.basename(sourceDir);
+    const zipPath = outputPath || path.join(path.dirname(sourceDir), `${dirName}.zip`);
+
+    const output = fs.createWriteStream(zipPath);
+    const archive = archiver('zip', {
+      zlib: { level: 6 },
+    });
+
+    output.on('close', () => {
+      resolve(zipPath);
+    });
+
+    archive.on('error', (err) => {
+      reject(err);
+    });
+
+    archive.pipe(output);
+    archive.directory(sourceDir, dirName);
+    archive.finalize();
+  });
+}
+
+module.exports = {
+  compressDirectory,
+};