dbdock 1.1.0 → 1.1.2

package/README.md

@@ -24,7 +24,7 @@ npx dbdock restore   # Restore backup
 - **Security** - AES-256 encryption, Brotli compression
 - **Retention Policies** - Automatic cleanup by count/age with safety nets
 - **Smart UX** - Intelligent filtering for 100+ backups, clear error messages
-- **Email Alerts** - SMTP notifications with custom templates
+- **Alerts** - Email (SMTP) and Slack notifications for backups (CLI & Programmatic)
 - **TypeScript Native** - Full type safety for programmatic usage
 - **Automation** - Cron schedules, auto-cleanup after backups
 
@@ -33,7 +33,7 @@ npx dbdock restore   # Restore backup
 **Global Installation (Recommended):**
 
 ```bash
-npm install -g dbdock-cli
+npm install -g dbdock
 
 dbdock init      # Use directly
 dbdock backup
@@ -57,7 +57,7 @@ Interactive setup wizard that creates `dbdock.config.json` with:
 - Database connection (host, port, credentials)
 - Storage provider (Local, S3, R2, Cloudinary)
 - Encryption/compression settings
-- Email alerts (optional)
+- Email and Slack alerts (optional)
 
 Auto-adds config to `.gitignore` to protect credentials.
 
@@ -115,6 +115,15 @@ Progress:
 - Date range (24h, 7d, 30d, 90d, custom)
 - Search by keyword/ID
 
+**Migration Support:**
+
+You can choose to restore to a **New Database Instance** during the restore process. This is perfect for migrating data between servers (e.g., from staging to production or local to cloud).
+
+1. Run `npx dbdock restore`
+2. Select a backup
+3. Choose "New Database Instance (Migrate)"
+4. Enter connection details for the target database
+
 Shows database stats and requires confirmation before restore.
 
 ### `npx dbdock list`
@@ -210,7 +219,7 @@ dbdock schedule
 - Every month (1st): `0 0 1 * *`
 - Custom cron expression
 
-**⚠️ Important:** Schedules only execute when DBDock is integrated into your NestJS application (see Programmatic Usage below). The CLI is for configuration only.
+**⚠️ Important:** Schedules only execute when DBDock is integrated into your Node.js application (see Programmatic Usage below). The CLI is for configuration only.
 
 ## Configuration
 
@@ -367,127 +376,330 @@ Automatic cleanup to prevent storage bloat from frequent backups:
 
 ## Programmatic Usage
 
-### NestJS Integration
+Use DBDock in your Node.js application to create backups programmatically. You don't need to understand NestJS internals - DBDock provides a simple API that works with any Node.js backend.
 
-```typescript
-import { Module } from '@nestjs/common';
-import { DBDockModule } from 'dbdock';
-
-@Module({
-  imports: [
-    DBDockModule.forRoot({
-      database: {
-        type: 'postgres',
-        host: 'localhost',
-        port: 5432,
-        username: 'postgres',
-        password: process.env.DB_PASSWORD,
-        database: 'myapp',
-      },
-      storage: {
-        provider: 's3',
-        s3: {
-          bucket: 'my-backups',
-          region: 'us-east-1',
-          accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-        },
-      },
-      backup: {
-        compression: { enabled: true, level: 6 },
-        encryption: { enabled: true, key: process.env.ENCRYPTION_KEY },
-        schedules: [
-          { name: 'Daily Backup', cron: '0 2 * * *', enabled: true },
-          { name: 'Weekly Full', cron: '0 0 * * 0', enabled: true },
-        ],
-      },
-    }),
-  ],
-})
-export class AppModule {}
+### Basic Setup
+
+First, install DBDock:
+
+```bash
+npm install dbdock
 ```
 
-### Creating and Restoring Backups
+Make sure you have `dbdock.config.json` configured (run `npx dbdock init` first). DBDock reads all configuration from this file automatically.
 
-```typescript
-import { BackupService } from 'dbdock';
+### How It Works
 
-@Injectable()
-export class MyService {
-  constructor(private backupService: BackupService) {}
+DBDock uses a simple initialization pattern:
 
-  async createBackup() {
-    const result = await this.backupService.createBackup({
-      compress: true,
-      encrypt: true,
-    });
+1. Call `createDBDock()` to initialize DBDock (reads from `dbdock.config.json`)
+2. Get the `BackupService` from the returned context using `.get(BackupService)`
+3. Use the service methods to create backups, list backups, etc.
 
-    console.log(`Backup created: ${result.metadata.id}`);
-    return result;
-  }
+Think of `createDBDock()` as a factory function that sets up everything for you based on your config file.
 
-  async restore(backupId: string) {
-    await this.backupService.restoreBackup(backupId);
-  }
+### Creating Backups
+
+```javascript
+const { createDBDock, BackupService } = require('dbdock');
+
+async function createBackup() {
+  const dbdock = await createDBDock();
+  const backupService = dbdock.get(BackupService);
+
+  const result = await backupService.createBackup({
+    format: 'plain', // 'custom' (binary), 'plain' (sql), 'directory', 'tar'
+    compress: true,
+    encrypt: true,
+  });
+
+  console.log(`Backup created: ${result.metadata.id}`);
+  console.log(`Size: ${result.metadata.formattedSize}`); // e.g. "108.3 KB"
+  console.log(`Path: ${result.storageKey}`);
+  
+  return result;
 }
+
+createBackup().catch(console.error);
 ```
 
-### Schedule Management API
+**Backup Options:**
 
-```typescript
-import { ScheduleManager } from 'dbdock';
+- `compress` - Enable/disable compression (default: from config)
+- `encrypt` - Enable/disable encryption (default: from config)
+- `format` - Backup format: `'custom'` (default), `'plain'`, `'directory'`, `'tar'`
+- `type` - Backup type: `'full'` (default), `'schema'`, `'data'`
 
-const scheduleManager = new ScheduleManager();
+### Listing Backups
 
-scheduleManager.addSchedule({
-  name: 'Hourly Backup',
-  cron: '0 * * * *',
-  enabled: true,
-});
+```javascript
+const { createDBDock, BackupService } = require('dbdock');
 
-const schedules = scheduleManager.getSchedules();
-console.log('All schedules:', schedules);
+async function listBackups() {
+  const dbdock = await createDBDock();
+  const backupService = dbdock.get(BackupService);
 
-scheduleManager.updateSchedule('Hourly Backup', {
-  cron: '0 */2 * * *',
-});
+  const backups = await backupService.listBackups();
+
+  console.log(`Found ${backups.length} backups:`);
+  backups.forEach(
+    (backup: {
+      id: string;
+      formattedSize: string;
+      startTime: string | Date;
+    }) => {
+      console.log(
+        `- ${backup.id} (${backup.formattedSize}, created: ${backup.startTime})`
+      );
+    }
+  );
 
-scheduleManager.enableSchedule('Daily Backup');
-scheduleManager.disableSchedule('Weekly Full');
+  return backups;
+}
 
-scheduleManager.removeSchedule('Old Schedule');
+listBackups().catch(console.error);
 ```
 
-### Complete Example with Schedules
+### Getting Backup Metadata
 
-```typescript
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import { ScheduleManager } from 'dbdock';
+```javascript
+const { createDBDock, BackupService } = require('dbdock');
 
-async function bootstrap() {
-  const scheduleManager = new ScheduleManager();
+async function getBackupInfo(backupId) {
+  const dbdock = await createDBDock();
+  const backupService = dbdock.get(BackupService);
 
-  scheduleManager.addSchedule({
-    name: 'Daily Backup',
-    cron: '0 2 * * *',
-    enabled: true,
+  const metadata = await backupService.getBackupMetadata(backupId);
+  
+  if (!metadata) {
+    console.log('Backup not found');
+    return null;
+  }
+  
+  console.log('Backup details:', {
+    id: metadata.id,
+    size: metadata.size,
+    created: metadata.startTime,
+    encrypted: !!metadata.encryption,
+    compressed: metadata.compression.enabled,
   });
+  
+  return metadata;
+}
 
-  scheduleManager.addSchedule({
-    name: 'Weekly Archive',
-    cron: '0 0 * * 0',
-    enabled: true,
-  });
+getBackupInfo('your-backup-id').catch(console.error);
+```
+
+**Note:** Restore functionality is currently only available via CLI (`npx dbdock restore`). Programmatic restore will be available in a future release.
+
+### Scheduling Backups
+
+DBDock doesn't include a built-in scheduler (to keep the package lightweight), but it's easy to schedule backups using `node-cron`.
+
+First, install `node-cron`:
+
+```bash
+npm install node-cron
+npm install --save-dev @types/node-cron
+```
 
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
+Then create a scheduler script (e.g., `scheduler.ts`):
 
-  console.log('Application started with scheduled backups');
+```typescript
+import { createDBDock, BackupService } from 'dbdock';
+import * as cron from 'node-cron';
+
+async function startScheduler() {
+  // Initialize DBDock
+  const dbdock = await createDBDock();
+  const backupService = dbdock.get(BackupService);
+
+  console.log('🚀 Backup scheduler started. Running every minute...');
+
+  // Schedule task to run every minute ('* * * * *')
+  // For every 5 minutes use: '*/5 * * * *'
+  // For every hour use: '0 * * * *'
+  cron.schedule('* * * * *', async () => {
+    try {
+      console.log('\n⏳ Starting scheduled backup...');
+      
+      const result = await backupService.createBackup({
+        format: 'plain', // Use 'plain' for SQL text, 'custom' for binary
+        compress: true,
+        encrypt: true,
+      });
+
+      console.log(`✅ Backup successful: ${result.metadata.id}`);
+      console.log(`📦 Size: ${result.metadata.formattedSize}`);
+      console.log(`📂 Path: ${result.storageKey}`);
+    } catch (error) {
+      console.error('❌ Backup failed:', error);
+    }
+  });
 }
 
-bootstrap();
+startScheduler().catch(console.error);
+```
+
+**Note:** The CLI `dbdock schedule` command manages configuration for external schedulers but does not run a daemon itself. Using `node-cron` as shown above is the recommended way to run scheduled backups programmatically.
+
+### Alerts
+ 
+DBDock can send notifications when backups complete (success or failure) via Email and Slack. Alerts work with both **programmatic usage** and **CLI commands**.
+ 
+**Configuration in `dbdock.config.json`:**
+ 
+```json
+{
+  "database": { ... },
+  "storage": { ... },
+  "backup": { ... },
+  "alerts": {
+    "email": {
+      "enabled": true,
+      "smtp": {
+        "host": "smtp.gmail.com",
+        "port": 587,
+        "secure": false,
+        "auth": {
+          "user": "your-email@gmail.com",
+          "pass": "your-app-password"
+        }
+      },
+      "from": "backups@yourapp.com",
+      "to": ["admin@yourapp.com", "devops@yourapp.com"]
+    },
+    "slack": {
+      "enabled": true,
+      "webhookUrl": "https://hooks.slack.com/services/..."
+    }
+  }
+}
+```
+ 
+**Slack Configuration:**
+ 
+1. Create a Slack App or use an existing one.
+2. Enable "Incoming Webhooks".
+3. Create a new Webhook URL for your channel.
+4. Run `npx dbdock init` and paste the URL when prompted.
+ 
+**SMTP Provider Examples:**
+ 
+_Gmail:_
+```json
+{
+  "smtp": {
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "secure": false,
+    "auth": {
+      "user": "your-email@gmail.com",
+      "pass": "your-app-password"
+    }
+  }
+}
+```
+ 
+> **Note:** For Gmail, you need to [create an App Password](https://support.google.com/accounts/answer/185833) instead of using your regular password.
+ 
+_SendGrid:_
+```json
+{
+  "smtp": {
+    "host": "smtp.sendgrid.net",
+    "port": 587,
+    "secure": false,
+    "auth": {
+      "user": "apikey",
+      "pass": "YOUR_SENDGRID_API_KEY"
+    }
+  }
+}
+```
+ 
+_AWS SES:_
+```json
+{
+  "smtp": {
+    "host": "email-smtp.us-east-1.amazonaws.com",
+    "port": 587,
+    "secure": false,
+    "auth": {
+      "user": "YOUR_SMTP_USERNAME",
+      "pass": "YOUR_SMTP_PASSWORD"
+    }
+  }
+}
+```
+ 
+_Mailgun:_
+```json
+{
+  "smtp": {
+    "host": "smtp.mailgun.org",
+    "port": 587,
+    "secure": false,
+    "auth": {
+      "user": "postmaster@your-domain.mailgun.org",
+      "pass": "YOUR_MAILGUN_SMTP_PASSWORD"
+    }
+  }
+}
+```
+ 
+**Using Alerts Programmatically:**
+ 
+Once configured in `dbdock.config.json`, alerts are sent automatically when you create backups programmatically:
+ 
+```javascript
+const { createDBDock, BackupService } = require('dbdock');
+ 
+async function createBackupWithAlerts() {
+  const dbdock = await createDBDock();
+  const backupService = dbdock.get(BackupService);
+ 
+  // Alerts will be sent automatically after backup completes
+  const result = await backupService.createBackup({
+    compress: true,
+    encrypt: true,
+  });
+ 
+  console.log(`Backup created: ${result.metadata.id}`);
+  // Alerts sent to configured channels
+}
+ 
+createBackupWithAlerts().catch(console.error);
 ```
+ 
+**Alert Content:**
+ 
+Success alerts include:
+- Backup ID
+- Database name
+- Size (original and compressed)
+- Duration
+- Storage location
+- Encryption status
+ 
+Failure alerts include:
+- Error message
+- Database details
+- Timestamp
+- Helpful troubleshooting tips
+ 
+**Testing Alert Configuration:**
+ 
+Run `npx dbdock test` to validate your configuration without creating a backup.
+ 
+**Important Notes:**
+ 
+- ✅ Alerts work with programmatic usage (`createBackup()`)
+- ✅ Alerts work with scheduled backups (cron jobs in your app)
+- ✅ Alerts work with CLI commands (`npx dbdock backup`)
+- Configuration is read from `dbdock.config.json` automatically
+- Multiple recipients supported in the `to` array for email
+- Alerts are sent asynchronously (won't block backup completion)
 
 ## Requirements
 

package/dist/alerts/alert.service.d.ts

@@ -18,6 +18,7 @@ export declare class AlertService {
     }): Promise<void>;
     sendStorageErrorAlert(error: Error): Promise<void>;
     private sendAlert;
+    private sendSlackAlert;
     private sendEmail;
     verifyConnection(): Promise<boolean>;
 }

package/dist/alerts/alert.service.js

@@ -41,6 +41,9 @@ var __importStar = (this && this.__importStar) || (function () {
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 var AlertService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AlertService = void 0;
@@ -49,6 +52,7 @@ const nodemailer = __importStar(require("nodemailer"));
 const config_service_1 = require("../config/config.service");
 const alert_types_1 = require("./alert.types");
 const alert_templates_1 = require("./alert-templates");
+const node_fetch_1 = __importDefault(require("node-fetch"));
 let AlertService = AlertService_1 = class AlertService {
     configService;
     logger = new common_1.Logger(AlertService_1.name);
@@ -61,23 +65,28 @@ let AlertService = AlertService_1 = class AlertService {
     initializeTransporter() {
         const alertsConfig = this.configService.get('alerts');
         if (!alertsConfig) {
-            this.logger.log('Email alerts disabled - no alerts configuration found');
+            this.logger.log('Alerts disabled - no alerts configuration found');
             return;
         }
-        try {
-            this.transporter = nodemailer.createTransport({
-                host: alertsConfig.smtpHost,
-                port: alertsConfig.smtpPort,
-                secure: alertsConfig.smtpPort === 465,
-                auth: {
-                    user: alertsConfig.smtpUser,
-                    pass: alertsConfig.smtpPass,
-                },
-            });
-            this.logger.log(`Email alerts enabled - configured for ${alertsConfig.smtpHost}:${alertsConfig.smtpPort}`);
+        if (alertsConfig.smtpHost) {
+            try {
+                this.transporter = nodemailer.createTransport({
+                    host: alertsConfig.smtpHost,
+                    port: alertsConfig.smtpPort,
+                    secure: alertsConfig.smtpPort === 465,
+                    auth: {
+                        user: alertsConfig.smtpUser,
+                        pass: alertsConfig.smtpPass,
+                    },
+                });
+                this.logger.log(`Email alerts enabled - configured for ${alertsConfig.smtpHost}:${alertsConfig.smtpPort}`);
+            }
+            catch (error) {
+                this.logger.error(`Failed to initialize email transporter: ${error.message}`);
+            }
         }
-        catch (error) {
-            this.logger.error(`Failed to initialize email transporter: ${error.message}`);
+        if (alertsConfig.slackWebhook) {
+            this.logger.log('Slack alerts enabled');
         }
     }
     setCustomTemplate(type, template) {
@@ -85,8 +94,6 @@ let AlertService = AlertService_1 = class AlertService {
         this.logger.log(`Custom template set for alert type: ${type}`);
     }
     async sendBackupSuccessAlert(metadata, downloadUrl) {
-        if (!this.transporter)
-            return;
         const context = {
             database: metadata.database,
             backupId: metadata.id,
@@ -104,8 +111,6 @@ let AlertService = AlertService_1 = class AlertService {
         });
     }
     async sendBackupFailureAlert(metadata, error) {
-        if (!this.transporter)
-            return;
         const context = {
             database: metadata.database,
             backupId: metadata.id,
@@ -120,8 +125,6 @@ let AlertService = AlertService_1 = class AlertService {
         });
     }
     async sendRetentionCleanupAlert(details) {
-        if (!this.transporter)
-            return;
         const context = {
             backupsDeleted: details.backupsDeleted,
             walFilesDeleted: details.walFilesDeleted,
@@ -134,8 +137,6 @@ let AlertService = AlertService_1 = class AlertService {
         });
     }
     async sendStorageErrorAlert(error) {
-        if (!this.transporter)
-            return;
         const context = {
             error: error.message,
             timestamp: new Date().toLocaleString(),
@@ -147,27 +148,88 @@ let AlertService = AlertService_1 = class AlertService {
         });
     }
     async sendAlert(alertContext) {
-        if (!this.transporter)
-            return;
         const alertsConfig = this.configService.get('alerts');
         if (!alertsConfig)
             return;
-        try {
-            const template = this.customTemplates[alertContext.type] ||
-                alert_templates_1.DEFAULT_TEMPLATES[alertContext.type];
-            const subject = (0, alert_templates_1.renderTemplate)(template.subject, alertContext.details || {});
-            const html = (0, alert_templates_1.renderTemplate)(template.body, alertContext.details || {});
-            const text = html.replace(/<[^>]*>/g, '');
-            await this.sendEmail({
-                to: alertsConfig.to,
-                subject,
-                html,
-                text,
-            });
-            this.logger.log(`Alert sent: ${alertContext.type} to ${alertsConfig.to.join(', ')}`);
+        if (this.transporter && alertsConfig.to) {
+            try {
+                const template = this.customTemplates[alertContext.type] ||
+                    alert_templates_1.DEFAULT_TEMPLATES[alertContext.type];
+                const subject = (0, alert_templates_1.renderTemplate)(template.subject, alertContext.details || {});
+                const html = (0, alert_templates_1.renderTemplate)(template.body, alertContext.details || {});
+                const text = html.replace(/<[^>]*>/g, '');
+                await this.sendEmail({
+                    to: alertsConfig.to,
+                    subject,
+                    html,
+                    text,
+                });
+                this.logger.log(`Email alert sent: ${alertContext.type} to ${alertsConfig.to.join(', ')}`);
+            }
+            catch (error) {
+                this.logger.error(`Failed to send email alert (${alertContext.type}): ${error.message}`);
+            }
         }
-        catch (error) {
-            this.logger.error(`Failed to send alert (${alertContext.type}): ${error.message}`);
+        if (alertsConfig.slackWebhook) {
+            try {
+                await this.sendSlackAlert(alertsConfig.slackWebhook, alertContext);
+                this.logger.log(`Slack alert sent: ${alertContext.type}`);
+            }
+            catch (error) {
+                this.logger.error(`Failed to send Slack alert (${alertContext.type}): ${error.message}`);
+            }
+        }
+    }
+    async sendSlackAlert(webhookUrl, context) {
+        let color = '#36a64f';
+        let title = 'DBDock Alert';
+        let text = '';
+        switch (context.type) {
+            case alert_types_1.AlertType.BACKUP_SUCCESS:
+                title = '✅ Backup Successful';
+                text = `Database: *${context.details?.database}*\nSize: ${context.details?.size} MB\nDuration: ${context.details?.duration}s`;
+                break;
+            case alert_types_1.AlertType.BACKUP_FAILURE:
+                color = '#dc3545';
+                title = '❌ Backup Failed';
+                text = `Database: *${context.details?.database}*\nError: ${context.details?.error}`;
+                break;
+            case alert_types_1.AlertType.RETENTION_CLEANUP:
+                color = '#17a2b8';
+                title = '🧹 Retention Cleanup';
+                text = `Deleted ${context.details?.backupsDeleted} backups\nFreed ${context.details?.spaceFreed} MB`;
+                break;
+            case alert_types_1.AlertType.STORAGE_ERROR:
+                color = '#ffc107';
+                title = '⚠️ Storage Error';
+                text = `Error: ${context.details?.error}`;
+                break;
+        }
+        const payload = {
+            attachments: [
+                {
+                    color,
+                    title,
+                    text,
+                    fields: Object.entries(context.details || {})
+                        .filter(([key]) => !['database', 'size', 'duration', 'error', 'backupsDeleted', 'spaceFreed'].includes(key))
+                        .map(([key, value]) => ({
+                        title: key.charAt(0).toUpperCase() + key.slice(1),
+                        value: String(value),
+                        short: true,
+                    })),
+                    footer: 'DBDock',
+                    ts: Math.floor(Date.now() / 1000),
+                },
+            ],
+        };
+        const response = await (0, node_fetch_1.default)(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            throw new Error(`Slack API error: ${response.statusText}`);
         }
     }
     async sendEmail(options) {