mongodb-snapshot

library1.4.1jsnpmunverified

mongodb-snapshot (v1.4.1) is a TypeScript-first library for dumping and restoring MongoDB databases between various data sources, including local files and other MongoDB instances. It provides a streaming, promise-based transfer mechanism using duplex connectors, with support for progress tracking via async iterators. The package is actively maintained on GitHub with monthly releases, and ships its own TypeScript definitions. Compared to mongodump/mongorestore, it offers programmatic control and in-process streaming without shell commands, and supports multi-target transfers (fan-out) efficiently. All operations require MongoDB instance access and local filesystem write permissions.

database storage

npm install mongodb-snapshot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-SNAPSHOT

mongodb-snapshot

databasejavascriptv1.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongoTransferer

✓ import { MongoTransferer } from 'mongodb-snapshot'

✗ const MongoTransferer = require('mongodb-snapshot')

ESM-only package; CommonJS require() will not work.

MongoDBDuplexConnector

✓ import { MongoDBDuplexConnector } from 'mongodb-snapshot'

✗ import MongoDBDuplexConnector from 'mongodb-snapshot'

Named export, not default.

LocalFileSystemDuplexConnector

✓ import { LocalFileSystemDuplexConnector } from 'mongodb-snapshot'

✗ import { LocalFileSystemDuplexConnector } from 'mongodb-snapshot/src'

Exported from the package root, not from a subpath.

Dumps a MongoDB database to a local .tar file using streaming connectors and progress reporting.

import { MongoTransferer, MongoDBDuplexConnector, LocalFileSystemDuplexConnector } from 'mongodb-snapshot'; async function dumpMongo2Localfile() { const mongo_connector = new MongoDBDuplexConnector({ connection: { uri: `mongodb://${process.env.MONGO_USER ?? ''}:${process.env.MONGO_PASS ?? ''}@${process.env.MONGO_HOST ?? 'localhost'}:${process.env.MONGO_PORT ?? '27017'}`, dbname: process.env.MONGO_DB ?? 'test', }, }); const localfile_connector = new LocalFileSystemDuplexConnector({ connection: { path: './backup.tar', }, }); const transferer = new MongoTransferer({ source: mongo_connector, targets: [localfile_connector], }); for await (const { total, write } of transferer) { console.log(`remaining bytes to write: ${total - write}`); } } dumpMongo2Localfile().catch(console.error);

Debug

Known issues

breakingRequires ESM module system; CommonJS require() throws error.

fix

Set 'type': 'module' in package.json or use .mjs extension.

affects: >=1.0.0

gotchaMongoDB connection URI must include auth credentials if authentication is enabled; otherwise connection fails with 'Authentication failed'.

fix

Ensure URI includes username:password@host:port/dbname or use a connection string with proper credentials.

affects: >=1.0.0

gotchaThe library uses mongodb driver's native stream; if MongoDB server version is incompatible, dump/restore may fail with 'MongoError: cannot connect'.

fix

Ensure compatible MongoDB server version (4.0+) and driver version (mongodb ^5.x).

affects: >=1.0.0

deprecatedUsing 'new MongoTransferer({...})' without 'await' may cause unhandled promise rejections.

fix

Always await the async iteration: for await (const progress of transferer) {...}

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , mongodb_snapshot_1.MongoTransferer) is not a constructor

Using CommonJS require() instead of ESM import.

fix

Change to 'import { MongoTransferer } from 'mongodb-snapshot' and ensure package.json has type: module.

MongoParseError: Invalid scheme, expected connection string to start with 'mongodb://' or 'mongodb+srv://'

The URI provided to MongoDBDuplexConnector is malformed or missing protocol.

fix

Ensure connection.uri starts with 'mongodb://' or 'mongodb+srv://'.

MongoError: E11000 duplicate key error collection: test.users index: email_1 dup key: { email: "foo@bar.com" }

Attempting to restore documents that violate a unique index in the target collection.

fix

Drop or clear the target collection before restore, or adjust the dump to exclude duplicates.

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

mongodboptionalCore dependency for MongoDB connections, provides the MongoClient and streams for data transfer.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/lihaibh/mongodb-snapshot ↗

packagemongodb-snapshot ↗

homepagehttps://github.com/lihaibh/mongodb-snapshot#readme ↗