db-backup-logging

Production-ready NPM package for database backup, request/response logging, and exception tracking.
Written in TypeScript. Supports CommonJS + ESM.

Installation

npm install db-backup-logging

Peer dependencies (must exist in your project):

npm install mongoose express

Optional (only if using S3 backups):

npm install @aws-sdk/client-s3

Optional (only if using automatic backup/cleanup schedulers):

npm install node-cron

Quick Start

1. Initialize (after mongoose.connect())

import { initializeNoticePackage } from 'db-backup-logging'

initializeNoticePackage({
  dbType: 'mongodb',
  dbUri: 'mongodb://localhost:27017/mydb',
  serviceName: 'my-api',
  environment: 'production',
  tables: {
    requestLogs: 'request_logs',
    errorLogs: 'error_logs',
    backupLogs: 'backup_logs',
  },
  // Optional — S3 backup
  aws: {
    enabled: true,
    bucketName: 'my-backups',
    region: 'ap-south-1',
    accessKeyId: 'YOUR_KEY',
    secretAccessKey: 'YOUR_SECRET',
  },
  // Optional — local backup
  local: {
    enabled: true,
    backupPath: './backups',
  },
})

2. Add Request Logger Middleware

import { requestLogger } from 'db-backup-logging'

// Add BEFORE your routes
app.use(requestLogger())

Logs: HTTP method, URL, headers, request body, response status, response body, response time (ms), user ID, IP, service name, environment, timestamp.

3. Add Error Middleware

import { errorMiddleware } from 'db-backup-logging'

// Add AFTER all routes
app.use(errorMiddleware())

This also automatically registers uncaughtException and unhandledRejection handlers on initialization.

4. Trigger Manual Backup

import { manualBackupTrigger } from 'db-backup-logging'

await manualBackupTrigger()

Note: Requires mongodump CLI installed on the machine.

5. Log Custom Errors

import { logCustomError } from 'db-backup-logging'

logCustomError(new Error('Payment failed'), {
  userId: 'user_123',
  requestContext: {
    method: 'POST',
    url: '/api/payments',
  },
})

6. Automatic Backup Scheduler

Requires node-cron installed in your project.

import { initBackupScheduler } from 'db-backup-logging'

// Call after initializeNoticePackage()
initBackupScheduler()

Schedule is resolved in priority order:

1. BACKUP_CRON_SCHEDULE / BACKUP_TIMEZONE env vars
2. config.backupCron passed to initializeNoticePackage()
3. Default: "0 2 * * *" (2 AM daily, UTC)

7. Automatic Log Cleanup Scheduler

Requires node-cron installed in your project.

import { initLogCleanupScheduler } from 'db-backup-logging'

// Call after initializeNoticePackage()
initLogCleanupScheduler()

Schedule and retention are resolved in priority order:

1. LOG_CLEANUP_CRON_SCHEDULE / LOG_CLEANUP_TIMEZONE / LOG_RETENTION_DAYS env vars
2. config.logCleanupCron passed to initializeNoticePackage()
3. Default: "0 3 * * *" (3 AM daily, UTC), 30 days retention

Full Config Reference

interface CronConfig {
  schedule: string    // Cron expression, e.g. "0 2 * * *"
  timezone?: string   // IANA timezone, e.g. "Asia/Kolkata"
  retentionDays?: number  // Days to keep (logCleanupCron only)
}

interface NoticeConfig {
  dbType: 'mongodb' | 'postgres' | 'mysql'
  dbUri: string                    // MongoDB connection URI
  schema?: string                  // Schema name (for SQL databases)
  serviceName?: string             // Your service/app name
  environment?: string             // e.g. 'production', 'staging'
  tables: {
    requestLogs: string            // Collection name for request logs
    errorLogs: string              // Collection name for error logs
    backupLogs: string             // Collection name for backup logs
  }
  aws?: { ... }                    // S3 config (optional)
  local?: { ... }                  // Local backup config (optional)
  backupCron?: CronConfig          // Auto backup schedule (optional)
  logCleanupCron?: CronConfig      // Log cleanup schedule (optional)
}

Environment Variables

| Variable | Description | Default | |---|---|---| | MONGO_URI | MongoDB connection URI | — | | BACKUP_PATH | Local backup directory | — | | BACKUP_CRON_SCHEDULE | Backup cron expression | 0 2 * * * | | BACKUP_TIMEZONE | Backup cron timezone | UTC | | LOG_CLEANUP_CRON_SCHEDULE | Log cleanup cron expression | 0 3 * * * | | LOG_CLEANUP_TIMEZONE | Log cleanup timezone | UTC | | LOG_RETENTION_DAYS | Days to retain logs | 30 |

Exported Modules

| Export | Type | Description | |---|---|---| | initializeNoticePackage(config) | Function | Initialize the package (call once at startup) | | requestLogger() | Middleware | Express middleware for request/response logging | | errorMiddleware() | Middleware | Express error-handling middleware | | logCustomError(error, context?) | Function | Manually log any error | | manualBackupTrigger() | Async Function | Trigger a database backup on demand | | initBackupScheduler() | Function | Start automatic backup cron job (requires node-cron) | | initLogCleanupScheduler() | Function | Start automatic log cleanup cron job (requires node-cron) |

All types are also exported: NoticeConfig, AWSConfig, LocalConfig, NoticeTables, CronConfig, RequestLogEntry, ErrorLogEntry, BackupLogEntry.

Notes

• Dedicated Connection: db-backup-logging establishes its own dedicated database connection using config.dbUri to ensure logging operations never compete with your main application's query pool (and to avoid npm link Mongoose duplication issues).
• Logging failures are silently handled — the host app will never crash due to a logging error.
• Exception handlers chain with existing handlers — they don't override them.
• mongodump must be installed on the machine for the backup feature to work.