SDK overview

Use DBdock programmatically in your Node.js app.

Everything the CLI does, you can do from code. DBdock exports a small NestJS-based module that works with any Node.js backend — you don’t need to understand NestJS to use it.

Install

npm install dbdock

The one pattern to learn

const { createDBDock, BackupService } = require('dbdock');

async function main() {
  const dbdock = await createDBDock();
  const backups = dbdock.get(BackupService);

  const result = await backups.createBackup({
    compress: true,
    encrypt: true,
  });

  console.log('Backup created:', result.metadata.id);
}

main().catch(console.error);

Three steps:

1. await createDBDock() — initializes DBdock (reads dbdock.config.json and env vars)
2. dbdock.get(ServiceClass) — fetches the service you need
3. Call methods on the service

Available services

BackupService

Create backups, list backups, get metadata.

StorageService

Direct access to the storage adapter (advanced).

CryptoService

Encrypt/decrypt arbitrary data (advanced).

AlertService

Send notifications programmatically.

TypeScript support

DBdock ships full type definitions. In TypeScript:

import { createDBDock, BackupService, type BackupMetadata } from 'dbdock';

async function main(): Promise<void> {
  const dbdock = await createDBDock();
  const backups = dbdock.get(BackupService);

  const result = await backups.createBackup({
    compress: true,
    encrypt: true,
  });

  const metadata: BackupMetadata = result.metadata;
  console.log(metadata.id);
}

Configuration

The SDK reads from the same sources as the CLI:

1. dbdock.config.json (path controlled by DBDOCK_CONFIG_PATH)
2. Environment variables (.env and .env.local)
3. Environment-only if no config file exists

No separate SDK configuration needed.

Lifecycle

createDBDock() returns a context. Internally it holds connections and caches. If you’re running a long-lived process, create it once and reuse it:

const dbdock = await createDBDock();  // once at startup
const backups = dbdock.get(BackupService);

// use `backups` across many backup operations

If you’re running in a short-lived context (CLI script, Lambda), creating per-invocation is fine.

What’s supported programmatically

Operation	CLI	SDK
Create backup	✅	✅
List backups	✅	✅
Get backup metadata	✅	✅
Delete backup	✅	❌ (CLI only for now)
Restore backup	✅	❌ (CLI only for now)
Cleanup (retention)	✅	✅
Send alerts	✅	✅
Cross-DB migration	✅	❌ (CLI only)
copydb	✅	❌ (CLI only)

Restore and delete programmatic APIs are planned — follow dbdock/dbdock#issues for updates.

See also

Creating backups

Full API for BackupService.createBackup().

Listing backups

Query the backup history.

Scheduling

Build a scheduler with node-cron.

Alerts

Use the alert system from code.