@byigitt/wbackup

Database backup package with webhook delivery. Backup MongoDB and PostgreSQL databases, then send them to Discord, Telegram, or any custom webhook.

Installation

npm install @byigitt/wbackup
# or
pnpm add @byigitt/wbackup

Requirements:

• Node.js 18+
• mongodump for MongoDB backups (install MongoDB Database Tools)
• pg_dump for PostgreSQL backups (install PostgreSQL client)

Quick Start

import { backup } from '@byigitt/wbackup';

await backup({
  database: 'mongodb',
  connectionString: 'mongodb://localhost:27017/mydb',
  webhook: {
    type: 'discord',
    url: 'https://discord.com/api/webhooks/YOUR_WEBHOOK_URL',
  },
});

Usage

Simple API

import { backup } from '@byigitt/wbackup';

// MongoDB to Discord
await backup({
  database: 'mongodb',
  connectionString: 'mongodb://localhost:27017/mydb',
  webhook: {
    type: 'discord',
    url: 'https://discord.com/api/webhooks/...',
    username: 'Backup Bot', // optional
  },
  compress: true,      // optional, default: true
  retainBackup: false, // optional, keep local file after upload
});

// PostgreSQL to Discord
await backup({
  database: 'postgresql',
  connectionString: 'postgresql://user:pass@localhost:5432/mydb',
  webhook: {
    type: 'discord',
    url: 'https://discord.com/api/webhooks/...',
  },
});

Fluent API

For more control, use the BackupManager class:

import { BackupManager } from '@byigitt/wbackup';

const result = await new BackupManager()
  .database('mongodb', {
    connectionString: 'mongodb://localhost:27017/mydb',
    database: 'mydb',           // optional: specific database
    collection: 'users',        // optional: specific collection
  })
  .delivery('discord', {
    webhookUrl: 'https://discord.com/api/webhooks/...',
    username: 'DB Backup',
    embedColor: 0x00ff00,       // green
    includeMetadata: true,
  })
  .compress(true)
  .retainBackup(false)
  .onProgress((phase, message) => {
    console.log(`[${phase}] ${message}`);
  })
  .onSuccess((result) => {
    console.log(`Backup completed in ${result.totalDuration}ms`);
  })
  .onError((error, phase) => {
    console.error(`Failed during ${phase}:`, error.message);
  })
  .run();

Supported Databases

MongoDB

Uses mongodump under the hood.

.database('mongodb', {
  connectionString: 'mongodb://user:pass@localhost:27017/mydb',
  database: 'mydb',                    // optional
  collection: 'users',                 // optional
  authenticationDatabase: 'admin',     // optional
  additionalArgs: ['--gzip'],          // optional: extra mongodump args
  compress: true,                      // gzip the archive
})

PostgreSQL

Uses pg_dump under the hood.

.database('postgresql', {
  connectionString: 'postgresql://user:pass@localhost:5432/mydb',
  format: 'custom',        // 'plain' | 'custom' | 'directory' | 'tar'
  schema: 'public',        // optional: specific schema
  table: 'users',          // optional: specific table
  dataOnly: false,         // optional: skip schema
  schemaOnly: false,       // optional: skip data
  clean: false,            // optional: add DROP statements
  additionalArgs: [],      // optional: extra pg_dump args
  compress: true,          // gzip (only for 'plain' format)
})

Supported Delivery Platforms

Discord

.delivery('discord', {
  webhookUrl: 'https://discord.com/api/webhooks/...',
  username: 'Backup Bot',     // optional
  avatarUrl: 'https://...',   // optional
  threadId: '123456789',      // optional: post to thread
  embedColor: 0x5865f2,       // optional: embed color
  includeMetadata: true,      // optional: show size, duration, etc.
})

Telegram

Telegram is included but not registered by default. Register it first:

import {
  BackupManager,
  registerDeliveryStrategy,
  createTelegramDeliveryStrategy
} from '@byigitt/wbackup';

// Register Telegram
registerDeliveryStrategy('telegram', createTelegramDeliveryStrategy);

// Use it
await new BackupManager()
  .database('mongodb', { connectionString: '...' })
  .delivery('telegram', {
    botToken: 'YOUR_BOT_TOKEN',
    chatId: 'YOUR_CHAT_ID',
    parseMode: 'HTML',           // 'HTML' | 'Markdown' | 'MarkdownV2'
    disableNotification: false,
    protectContent: false,
  })
  .run();

Adding Custom Strategies

Custom Database Strategy

import { BackupStrategy, registerBackupStrategy } from '@byigitt/wbackup';
import { z } from 'zod';

const MyConfigSchema = z.object({
  connectionString: z.string(),
  compress: z.boolean().default(true),
});

class MyDatabaseStrategy implements BackupStrategy<z.infer<typeof MyConfigSchema>> {
  readonly name = 'mydatabase';
  readonly configSchema = MyConfigSchema;

  async backup(config) {
    // Your backup logic here
    return {
      filePath: '/path/to/backup.sql',
      fileName: 'backup.sql',
      sizeBytes: 1024,
      database: 'mydb',
      createdAt: new Date(),
      compressed: config.compress,
      metadata: { type: 'mydatabase' },
    };
  }

  async cleanup(filePath) {
    // Delete temp file
  }
}

// Register it
registerBackupStrategy('mydatabase', () => new MyDatabaseStrategy());

// Use it
await new BackupManager()
  .database('mydatabase', { connectionString: '...' })
  .delivery('discord', { webhookUrl: '...' })
  .run();

Custom Delivery Strategy

import { DeliveryStrategy, registerDeliveryStrategy } from '@byigitt/wbackup';
import { z } from 'zod';

const SlackConfigSchema = z.object({
  webhookUrl: z.string().url(),
  channel: z.string(),
});

class SlackDeliveryStrategy implements DeliveryStrategy<z.infer<typeof SlackConfigSchema>> {
  readonly name = 'slack';
  readonly configSchema = SlackConfigSchema;
  readonly maxFileSizeBytes = 1024 * 1024 * 1024; // 1GB

  async deliver(config, backup) {
    // Your delivery logic here
    return {
      success: true,
      platform: 'slack',
      deliveredAt: new Date(),
    };
  }
}

// Register and use
registerDeliveryStrategy('slack', () => new SlackDeliveryStrategy());

API Reference

backup(options)

Simple function for quick backups.

| Option | Type | Required | Description | |--------|------|----------|-------------| | database | string | Yes | Database type: 'mongodb' or 'postgresql' | | connectionString | string | Yes | Database connection string | | databaseName | string | No | Specific database name | | webhook.type | string | Yes | Delivery type: 'discord' | | webhook.url | string | Yes | Webhook URL | | webhook.username | string | No | Bot username | | compress | boolean | No | Compress backup (default: true) | | retainBackup | boolean | No | Keep local file (default: false) |

BackupManager

Fluent builder for advanced usage.

| Method | Description | |--------|-------------| | .database(type, config) | Set database type and config | | .delivery(type, config) | Set delivery type and config | | .compress(boolean) | Enable/disable compression | | .retainBackup(boolean) | Keep local backup file | | .onProgress(callback) | Progress updates | | .onSuccess(callback) | Success handler | | .onError(callback) | Error handler | | .run() | Execute backup |

BackupResult

Returned after successful backup.

{
  filePath: string;      // Path to backup file
  fileName: string;      // Backup filename
  sizeBytes: number;     // File size
  database: string;      // Database name
  createdAt: Date;       // Backup timestamp
  compressed: boolean;   // Was compressed
  metadata: {            // Extra info
    type: string;
    duration: number;
    // ...
  };
}

Error Handling

import { BackupManager, BackupError } from '@byigitt/wbackup';

try {
  await new BackupManager()
    .database('mongodb', { connectionString: '...' })
    .delivery('discord', { webhookUrl: '...' })
    .run();
} catch (error) {
  if (error instanceof BackupError) {
    console.error(`Failed during ${error.phase}:`, error.message);
    // error.phase is 'backup' | 'delivery' | 'cleanup'
  }
}

File Size Limits

Large backups are automatically split into chunks:

| Platform | Max File Size | |----------|---------------| | Discord | 25 MB | | Telegram | 50 MB |

License

MIT