SDK overview - DBDock

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:

await createDBDock() — initializes DBDock (reads dbdock.config.json and env vars)
dbdock.get(ServiceClass) — fetches the service you need
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:

dbdock.config.json (path controlled by DBDOCK_CONFIG_PATH)
Environment variables (.env and .env.local)
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.

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.

​Install

​The one pattern to learn

​Available services