mongodb-backup-service 1.0.0

package/.env.example

@@ -0,0 +1,25 @@
+MONGO_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>?retryWrites=true&w=majority
+
+BACKUP_PROJECT_NAME=My Project
+
+BACKUP_STORAGE_PATH=./backups
+
+BACKUP_SCHEDULE_TYPE=daily
+BACKUP_SCHEDULE_TIME=02:00
+BACKUP_TIMEZONE=UTC
+
+BACKUP_EXCEL_ENABLED=true
+BACKUP_EXCLUDE_COLLECTIONS=sessions,temporaryLogs
+
+BACKUP_RETENTION_ENABLED=true
+BACKUP_RETENTION_DAYS=30
+
+BACKUP_EMAIL_ENABLED=true
+BACKUP_EMAIL_TO=admin@example.com
+
+BACKUP_SMTP_HOST=smtp.gmail.com
+BACKUP_SMTP_PORT=587
+BACKUP_SMTP_SECURE=false
+BACKUP_SMTP_USER=my-email@gmail.com
+BACKUP_SMTP_PASSWORD=my-app-password
+BACKUP_EMAIL_FROM=backup-service@myproject.com

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abishek K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# mongodb-backup-service
+
+Reusable Node.js service for automated MongoDB backups with scheduling, startup recovery, Excel export, retention, email notifications, and backup locking.
+
+## Key Features
+
+- **MongoDB Atlas Backup**: Automated `mongodump` execution supporting local and Atlas clusters.
+- **Gzip Archive**: Compresses database dumps natively via `mongodump --gzip`.
+- **Excel Export**: Secondary human-readable `.xlsx` export, streaming large collections efficiently.
+- **Collection Exclusion**: Skip unnecessary collections (e.g., sessions, temporary logs) from the Excel export.
+- **Advanced Scheduling**: Supports `daily`, `weekly`, and `monthly` CRON scheduling.
+- **Configurable Timezone**: Run backups according to your local timezone (e.g., `Asia/Kolkata`, `America/New_York`).
+- **Startup Missed-Backup Recovery**: Automatically detects and recovers missed scheduled backups if the Node.js service was offline.
+- **Backup Locking**: Ensures exactly-once execution and prevents concurrent backup collisions.
+- **Retention Cleanup**: Automatically prunes old backups to save storage space (keeps the N most recent backups).
+- **Email Notifications**: Detailed success/failure reports via SMTP, separating MongoDB and Excel statuses.
+- **Local Storage Abstraction**: Clean, organized date-based directory structure for all artefacts.
+- **CLI Tool**: Built-in `mongodb-backup` command for manual triggers and status checks.
+- **Metadata Tracking**: Detailed `metadata.json` for every backup run.
+- **Graceful Shutdown**: Safe `SIGINT`/`SIGTERM` handling to stop the scheduler cleanly.
+
+## Why this package exists
+
+Managing automated database backups in Node.js applications often leads to scattered shell scripts and cron jobs that lack proper error handling, monitoring, and idempotency. `mongodb-backup-service` provides a robust, in-process solution that you can seamlessly integrate into your existing Express or Node.js backend. It treats backups as a first-class feature with strong guarantees against duplicate runs and missed schedules.
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Express / Node Backend] -->|backupService.start| B(DatabaseBackupService)
+    B --> C{Scheduler}
+    C -->|Trigger| D(BackupManager)
+    B -->|Startup Recovery| D
+    
+    D -->|1. Acquire Lock| E[BackupLock]
+    D -->|2. Dump| F[MongoDump]
+    D -->|3. Export| G[ExcelExporter]
+    D -->|4. Clean| H[RetentionManager]
+    D -->|5. Notify| I[EmailNotifier]
+    
+    F --> J[(Storage: .gz)]
+    G --> K[(Storage: .xlsx)]
+    
+    subgraph Storage Directory
+    J
+    K
+    L[metadata.json]
+    end
+    
+    D -->|Writes| L
+```
+
+## Requirements
+
+- **Node.js**: `>=18.0.0`
+- **MongoDB Database Tools**: `mongodump` must be installed on the host system and available in the system `PATH`.
+- **MongoDB Connection**: A valid MongoDB URI (supports MongoDB Atlas).
+- **SMTP Server**: Required only if email notifications are enabled.
+
+## Installation
+
+```bash
+npm install mongodb-backup-service
+```
+
+## Configuration
+
+The service is configured using a JavaScript object, typically populated via environment variables (`.env`). Copy `.env.example` to `.env` in your project root.
+
+| Variable | Required | Description | Example Safe Value |
+|---|---|---|---|
+| `MONGO_URI` | Yes | MongoDB connection string. | `mongodb+srv://<user>:<pwd>@cluster...` |
+| `BACKUP_PROJECT_NAME` | No | Identifier for logs and emails. | `My Project` |
+| `BACKUP_STORAGE_PATH` | No | Local directory to save backups. | `./backups` |
+| `BACKUP_SCHEDULE_TYPE` | No | `daily`, `weekly`, or `monthly`. | `daily` |
+| `BACKUP_SCHEDULE_TIME` | No | Time to run backup (HH:MM). | `02:00` |
+| `BACKUP_TIMEZONE` | No | Valid IANA Timezone. | `UTC` |
+| `BACKUP_EXCEL_ENABLED` | No | Enable/disable Excel export. | `true` |
+| `BACKUP_EXCLUDE_COLLECTIONS` | No | Comma-separated collections to skip in Excel. | `sessions,temporaryLogs` |
+| `BACKUP_RETENTION_ENABLED` | No | Enable/disable cleanup of old backups. | `true` |
+| `BACKUP_RETENTION_DAYS` | No | Number of most recent backups to keep. | `30` |
+| `BACKUP_EMAIL_ENABLED` | No | Enable/disable SMTP notifications. | `true` |
+| `BACKUP_EMAIL_TO` | No | Alert recipient address. | `admin@example.com` |
+| `BACKUP_SMTP_HOST` | No | SMTP server hostname. | `smtp.gmail.com` |
+| `BACKUP_SMTP_PORT` | No | SMTP port (e.g., 587, 465). | `587` |
+| `BACKUP_SMTP_SECURE` | No | Use TLS (true for 465, false for 587). | `false` |
+| `BACKUP_SMTP_USER` | No | SMTP username. | `user@gmail.com` |
+| `BACKUP_SMTP_PASSWORD` | No | SMTP password/App Password. | `xxxx-xxxx-xxxx-xxxx` |
+| `BACKUP_EMAIL_FROM` | No | Sender address for alerts. | `backup@myproject.com` |
+
+> **Security Note:** Never commit your real `.env` file containing database credentials or SMTP passwords to version control.
+
+## Express Backend Integration
+
+Integrate the backup service into your existing Node.js or Express application lifecycle:
+
+```javascript
+require('dotenv').config();
+const express = require('express');
+const backupService = require('mongodb-backup-service');
+
+const app = express();
+
+// 1. Configure and start the backup service
+backupService.start({
+    mongoUri: process.env.MONGO_URI,
+    projectName: process.env.BACKUP_PROJECT_NAME || 'My App',
+    storage: { path: process.env.BACKUP_STORAGE_PATH || './backups' },
+    schedule: {
+        type: process.env.BACKUP_SCHEDULE_TYPE || 'daily',
+        time: process.env.BACKUP_SCHEDULE_TIME || '02:00',
+        timezone: process.env.BACKUP_TIMEZONE || 'UTC'
+    },
+    // ... include excel, retention, and email configs ...
+});
+
+const server = app.listen(3000, () => {
+    console.log('Server running on port 3000');
+});
+
+// 2. Ensure graceful shutdown
+const shutdown = () => {
+    console.log('Shutting down server...');
+    backupService.stop(); // Stops the scheduler cleanly
+    server.close(() => {
+        process.exit(0);
+    });
+};
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+```
+
+## Scheduling
+
+The internal scheduler uses standard cron expressions based on your configuration:
+- `daily`: Runs every day at the specified `time`.
+- `weekly`: Requires a `day` (e.g., `sunday`) and `time`.
+- `monthly`: Requires a `day` (e.g., `1` for the 1st of the month) and `time`.
+
+The `timezone` parameter ensures that Daylight Saving Time and regional offsets are respected.
+
+## Startup Missed-Backup Recovery
+
+If your Node.js application is stopped or crashes during the scheduled backup window, the backup will not run while the process is offline. 
+
+To prevent data gaps, `mongodb-backup-service` performs a **Startup Recovery Check** when you call `backupService.start()`. It calculates the date of the most recently expected scheduled backup. If the backup directory for that date is missing, or its metadata indicates it did not complete successfully, the service will immediately trigger a recovery backup in the background.
+
+## Backup Locking / Duplicate Protection
+
+To prevent overlapping backups (e.g., a manual trigger coinciding with a scheduled run, or a recovery run overlapping with a cron tick), the service utilizes a file-based lock (`.backup.lock`). 
+
+This ensures **exactly-once execution**. If a backup is already in progress, any subsequent trigger (cron, recovery, or manual) will be safely rejected, logging a warning rather than corrupting the archive.
+
+## Backup Directory Structure
+
+Backups are neatly organized by date (in the configured timezone) within the storage path.
+
+```text
+backups/
+└── 2026-09-10/
+    ├── mongodb.archive.gz   # Compressed mongodump output
+    ├── database.xlsx        # Human-readable export
+    └── metadata.json        # Execution report
+```
+
+### Metadata
+
+The `metadata.json` file tracks the execution status without exposing any sensitive credentials. It contains:
+- `projectName` and `backupDate`
+- `startedAt`, `completedAt`, and `durationMs`
+- `status`: Overall backup status (`success` or `failed`)
+- `mongoDump`: Specific status, filename, and error (if any)
+- `excel`: Specific status, filename, and error (if any)
+
+## Excel Export
+
+When `excel.enabled` is `true`, the service exports your database to `database.xlsx`:
+- **One Sheet per Collection**: Each MongoDB collection becomes a separate worksheet.
+- **Dynamic Columns**: Columns are discovered dynamically as documents are streamed.
+- **Data Types**: Dates are preserved. `ObjectId`s are converted to strings. Nested objects and arrays are flattened into JSON strings to fit in Excel cells.
+- **Exclusions**: Use `excludeCollections` to skip large or irrelevant collections (like sessions).
+
+## Retention
+
+When `retention.enabled` is `true`, the `RetentionManager` runs at the end of every successful backup. It scans the storage directory and keeps the `N` most recent backup directories (where `N` is `retention.days`), deleting older directories to prevent disk exhaustion.
+
+## Email Notifications
+
+When `email.enabled` is `true`, an SMTP email is dispatched upon backup completion. The email clearly delineates the overall status, the MongoDB dump status, and the Excel export status.
+
+If the email notification itself fails to send (e.g., invalid SMTP credentials), the error is logged, but it **does not** mark the backup as failed in `metadata.json`, ensuring the actual data archiving process remains resilient.
+
+## CLI
+
+The package includes a command-line interface for manual administration. Ensure your `.env` is present in the directory where you run the commands.
+
+```bash
+# Manually trigger a backup right now
+npx mongodb-backup backup
+
+# Check the status of today's backup
+npx mongodb-backup status
+
+# List all available backup dates on disk
+npx mongodb-backup list
+
+# Manually trigger retention cleanup
+npx mongodb-backup cleanup
+
+# View help
+npx mongodb-backup help
+```
+
+## Security
+
+- **`.env`**: Always add `.env` and `backups/` to your `.gitignore`.
+- **Metadata**: No MongoDB URIs, passwords, or SMTP credentials are ever written to `metadata.json` or log files.
+- **Storage**: Ensure the host environment has appropriate file permissions for the `backups/` directory.
+
+## Testing
+
+The package includes a comprehensive suite of unit and integration tests covering scheduling, locking, database operations, and failure scenarios.
+
+```bash
+npm test
+```
+*(Currently 60/60 tests passing)*
+
+## V1 Scope
+
+Version 1 is designed specifically for single-node or replica-set MongoDB deployments (including Atlas) backing Node.js applications, utilizing local disk storage for artefacts and standard SMTP for notifications.
+
+## Limitations
+
+- **System Dependency**: Requires `mongodump` binary to be installed on the host machine.
+- **Storage**: Currently only supports local filesystem storage.
+- **Restore**: Does not currently include automated `mongorestore` functionality; archives must be restored manually.
+
+## Roadmap
+
+*Future considerations (Not yet implemented):*
+- Support for Cloud Storage (AWS S3, Google Drive, Azure Blob).
+- Automated restore workflows.
+- Webhook integrations (Slack/Discord alerts).
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+require('dotenv').config();
+const backup = require('../src/index');
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+// Load config from environment for CLI usage
+const config = {
+    mongoUri: process.env.MONGO_URI,
+    projectName: process.env.BACKUP_PROJECT_NAME || 'CLI Backup',
+
+    storage: {
+        path: process.env.BACKUP_STORAGE_PATH || './backups'
+    },
+
+    schedule: {
+        type: process.env.BACKUP_SCHEDULE_TYPE || 'daily',
+        time: process.env.BACKUP_SCHEDULE_TIME || '02:00',
+        timezone: process.env.BACKUP_TIMEZONE || Intl.DateTimeFormat().resolvedOptions().timeZone
+    },
+
+    excel: {
+        enabled: process.env.BACKUP_EXCEL_ENABLED === 'true',
+        excludeCollections: (process.env.BACKUP_EXCLUDE_COLLECTIONS || '').split(',').filter(c => c.trim() !== '')
+    },
+
+    retention: {
+        enabled: process.env.BACKUP_RETENTION_ENABLED === 'true',
+        days: parseInt(process.env.BACKUP_RETENTION_DAYS || '30', 10)
+    },
+
+    // ── Email — was missing entirely; caused email.enabled to always be false ──
+    email: {
+        enabled: process.env.BACKUP_EMAIL_ENABLED === 'true',
+        to:       process.env.BACKUP_EMAIL_TO       || '',
+        from:     process.env.BACKUP_EMAIL_FROM     || '',
+        host:     process.env.BACKUP_SMTP_HOST      || '',
+        port:     parseInt(process.env.BACKUP_SMTP_PORT || '587', 10),
+        secure:   process.env.BACKUP_SMTP_SECURE    === 'true',
+        user:     process.env.BACKUP_SMTP_USER      || '',
+        password: process.env.BACKUP_SMTP_PASSWORD  || ''
+    }
+};
+
+async function run() {
+    try {
+        // Only commands that actually touch MongoDB need a full config load with mongoUri
+        const requiresMongoUri = ['backup'];
+        
+        if (requiresMongoUri.includes(command)) {
+            if (!config.mongoUri) {
+                console.error("Error: MONGO_URI environment variable is required for this command.");
+                process.exit(1);
+            }
+            const configManager = require('../src/config/config');
+            configManager.load(config);
+        } else if (command !== 'help') {
+            // For list/status/cleanup, load a minimal config without requiring mongoUri
+            // We only need storage.path; set a dummy uri to pass validation
+            const configManager = require('../src/config/config');
+            try {
+                configManager.load({ ...config, mongoUri: config.mongoUri || 'mongodb://localhost:27017/__cli_readonly' });
+            } catch (e) {
+                // ignore email validation errors for read-only commands
+            }
+        }
+
+        switch (command) {
+            case 'backup':
+                console.log("Starting manual backup...");
+                const success = await backup.createBackup();
+                if (success) {
+                    console.log("Backup completed successfully.");
+                } else {
+                    console.error("Backup failed.");
+                    process.exit(1);
+                }
+                break;
+
+            case 'status':
+                const status = backup.getStatus();
+                if (status) {
+                    console.log(JSON.stringify(status, null, 2));
+                } else {
+                    console.log("No backup found for today.");
+                }
+                break;
+
+            case 'list':
+                const backups = backup.listBackups();
+                if (backups.length > 0) {
+                    console.log("Available backups:");
+                    backups.forEach(b => console.log(`- ${b}`));
+                } else {
+                    console.log("No backups found.");
+                }
+                break;
+
+            case 'cleanup':
+                console.log("Running retention cleanup...");
+                await backup.cleanup();
+                console.log("Cleanup completed.");
+                break;
+
+            case 'help':
+            default:
+                console.log(`
+Usage: mongodb-backup <command>
+
+Commands:
+  backup   - Manually trigger a backup
+  status   - Show status of today's backup
+  list     - List available backups
+  cleanup  - Run retention cleanup
+  help     - Show this help message
+                `);
+                break;
+        }
+    } catch (error) {
+        console.error("CLI error:", error);
+        process.exit(1);
+    }
+}
+
+run();

package/examples/basic-usage.js

@@ -0,0 +1,51 @@
+require('dotenv').config();
+const backup = require('../src/index');
+
+// Setup process signal handlers for graceful shutdown
+process.on('SIGINT', () => {
+    console.log("Shutting down backup service...");
+    backup.stop();
+    process.exit(0);
+});
+
+// Configure and start the backup service
+backup.start({
+    // Using environment variables or fallback to defaults
+    mongoUri: process.env.MONGO_URI,
+    
+    projectName: process.env.BACKUP_PROJECT_NAME || 'Example Backend',
+
+    storage: {
+        path: process.env.BACKUP_STORAGE_PATH || './backups'
+    },
+
+    schedule: {
+        type: process.env.BACKUP_SCHEDULE_TYPE || 'daily',
+        time: process.env.BACKUP_SCHEDULE_TIME || '02:00',
+        timezone: process.env.BACKUP_TIMEZONE || Intl.DateTimeFormat().resolvedOptions().timeZone
+    },
+
+    excel: {
+        enabled: process.env.BACKUP_EXCEL_ENABLED === 'true',
+        excludeCollections: (process.env.BACKUP_EXCLUDE_COLLECTIONS || '').split(',').filter(c => c.trim() !== '')
+    },
+
+    retention: {
+        enabled: process.env.BACKUP_RETENTION_ENABLED === 'true',
+        days: parseInt(process.env.BACKUP_RETENTION_DAYS || '30', 10)
+    },
+
+    email: {
+        enabled: process.env.BACKUP_EMAIL_ENABLED === 'true',
+        to: process.env.BACKUP_EMAIL_TO,
+        host: process.env.BACKUP_SMTP_HOST,
+        port: parseInt(process.env.BACKUP_SMTP_PORT || '587', 10),
+        secure: process.env.BACKUP_SMTP_SECURE === 'true',
+        user: process.env.BACKUP_SMTP_USER,
+        password: process.env.BACKUP_SMTP_PASSWORD,
+        from: process.env.BACKUP_EMAIL_FROM
+    }
+});
+
+console.log("Backup service started. It is running in the background and will trigger based on the schedule.");
+console.log("You can also trigger a manual backup using the CLI: npx database-backup backup");

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "mongodb-backup-service",
+  "version": "1.0.0",
+  "description": "Reusable Node.js service for automated MongoDB backups with scheduling, startup recovery, Excel export, retention, email notifications, and backup locking.",
+  "main": "src/index.js",
+  "bin": {
+    "mongodb-backup": "bin/cli.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "start": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "mongodb",
+    "mongodb-backup",
+    "mongodb-atlas",
+    "backup",
+    "database-backup",
+    "nodejs",
+    "automated-backup",
+    "mongodump",
+    "scheduler",
+    "disaster-recovery",
+    "excel",
+    "export"
+  ],
+  "author": "Abishek K",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abishek6702/Automated_DB_Backup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Abishek6702/Automated_DB_Backup/issues"
+  },
+  "homepage": "https://github.com/Abishek6702/Automated_DB_Backup#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0",
+    "mongodb": "^7.6.0",
+    "node-cron": "^4.0.0",
+    "nodemailer": "^10.0.0"
+  },
+  "devDependencies": {
+    "dotenv": "^17.4.2",
+    "jest": "^30.5.1"
+  }
+}

package/src/config/config.js

@@ -0,0 +1,49 @@
+const defaults = require('./defaults');
+
+class ConfigManager {
+    constructor() {
+        this.config = { ...defaults };
+    }
+
+    load(userConfig = {}) {
+        if (!userConfig.mongoUri) {
+            throw new Error("mongoUri is required for database-backup-package");
+        }
+
+        this.config = {
+            ...defaults,
+            ...userConfig,
+            storage: {
+                ...defaults.storage,
+                ...(userConfig.storage || {})
+            },
+            schedule: {
+                ...defaults.schedule,
+                ...(userConfig.schedule || {})
+            },
+            excel: {
+                ...defaults.excel,
+                ...(userConfig.excel || {})
+            },
+            email: {
+                ...defaults.email,
+                ...(userConfig.email || {})
+            },
+            retention: {
+                ...defaults.retention,
+                ...(userConfig.retention || {})
+            }
+        };
+
+        // If email is enabled, 'to' is required
+        if (this.config.email.enabled && !this.config.email.to) {
+            throw new Error("email.to is required when email notifications are enabled");
+        }
+    }
+
+    get() {
+        return this.config;
+    }
+}
+
+module.exports = new ConfigManager();

package/src/config/defaults.js

@@ -0,0 +1,29 @@
+module.exports = {
+    projectName: "Unknown Project",
+    storage: {
+        path: "./backups"
+    },
+    schedule: {
+        type: "daily",
+        time: "02:00",
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+    },
+    excel: {
+        enabled: true,
+        excludeCollections: []
+    },
+    email: {
+        enabled: false,
+        host: "localhost",
+        port: 25,
+        secure: false,
+        user: "",
+        password: "",
+        to: "",
+        from: "backup@localhost"
+    },
+    retention: {
+        enabled: true,
+        days: 30
+    }
+};

package/src/core/backupLock.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+const logger = require('../utils/logger');
+const DateUtils = require('../utils/dateUtils');
+
+class BackupLock {
+    constructor(storageBasePath) {
+        this.lockFile = path.join(storageBasePath, 'backup.lock');
+        // Lock expiration in ms (e.g., 2 hours). If a lock is older than this, it's considered stale.
+        this.staleMs = 2 * 60 * 60 * 1000;
+    }
+
+    acquire() {
+        if (fs.existsSync(this.lockFile)) {
+            const stats = fs.statSync(this.lockFile);
+            const age = Date.now() - stats.mtimeMs;
+            
+            if (age > this.staleMs) {
+                logger.warn("Found stale backup lock. Removing it and continuing.");
+                this.release();
+            } else {
+                logger.error("Another backup is currently in progress. Lock found.");
+                return false;
+            }
+        }
+        
+        try {
+            fs.writeFileSync(this.lockFile, JSON.stringify({
+                lockedAt: DateUtils.getIsoString(),
+                pid: process.pid
+            }), { flag: 'wx' });
+            return true;
+        } catch (error) {
+            logger.error("Failed to acquire backup lock.");
+            return false;
+        }
+    }
+
+    release() {
+        if (fs.existsSync(this.lockFile)) {
+            try {
+                fs.unlinkSync(this.lockFile);
+            } catch (error) {
+                logger.error("Failed to release backup lock.");
+            }
+        }
+    }
+}
+
+module.exports = BackupLock;