mongopatch

library2.0.2jsnpmunverified

MongoDB patching tool (v2.0.2) for declarative document migration via small, versioned JavaScript patches. Enables updates with query filtering, before/after hooks, and diff tracking. Current stable release is 2.0.2 (last updated 2018), with critical warnings about broken tests on MongoDB 2.6 and 3.4. Maintained primarily for internal use by debitoor. Release cadence is low; no new versions in several years. Not actively maintained. Differentiator: simple, git-friendly migration approach vs. mongodb-migrate or db-migrate.

database

npm install mongopatch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOPATCH

mongopatch

databasejavascriptv2.0.2

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.

patch client usage

✓ const patch = require('mongopatch'); patch.run(...)

✗ import { run } from 'mongopatch'

mongopatch is CommonJS-only; no ESM or named exports

patch for migration script

✓ module.exports = function(patch) { patch.version('0.1.0'); ... }

✗ module.exports = function(patch) { patch.version = ... }

Patch functions receive a `patch` object; `patch.version()` is a method, not a property

patch.update callback

✓ patch.update('users', { query }, function(doc, cb) { cb(null, update); })

✗ patch.update('users', { query }, function(doc, cb) { cb(null, updateQuery) }) // update must be full document or valid MongoDB update operator

The second argument to callback must be a valid MongoDB update operator (e.g., $set) or the full replacement document

Demonstrates how to create and run a simple migration patch using mongopatch CLI: renames a field in all user documents.

// Install: npm install -g mongopatch // Create a patch file, e.g., patches/001-rename-field.js module.exports = function(patch) { patch.version('0.1.0'); patch.update('users', { oldField: { $exists: true } }, function(doc, callback) { doc.newField = doc.oldField; delete doc.oldField; callback(null, doc); }); }; // Run: mongopatch --db mongodb://localhost:27017/mydb patches/001-rename-field.js

Debug

Known issues

breakingBroken tests with MongoDB 2.6 and 3.4 – may cause data corruption or incomplete updates

fix

Test thoroughly on your MongoDB version; avoid production on unsupported versions

affects: >=2.0.0

gotchaPatch version call is required but version string is not validated – can lead to inconsistent migration states

fix

Always call patch.version() with a semver string; track versions manually

affects: >=1.0.0

gotchaDry-run mode is not supported – running a patch directly modifies the database

fix

Backup the database or use a test environment before running patches

affects: >=1.0.0

deprecatedProject is unmaintained since 2018; no fixes for newer MongoDB drivers or features

fix

Consider alternatives like mongodb-migrate or write custom migration scripts

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'mongopatch'

Not installed or global module not in PATH

fix

Install globally: npm install -g mongopatch

Error: Invalid document

Callback returned an invalid update object (e.g., missing $set or malformed)

fix

Ensure the callback second argument is a valid MongoDB update operator or the full document

patch.version is not a function

Patch function does not receive proper patch object (e.g., using wrong export pattern)

fix

Export a function that takes `patch` as argument and call patch.version() inside

MongoError: server instance in invalid state

MongoDB connection issue or version incompatibility

fix

Check MongoDB version compatibility; ensure server is running and accessible

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

mongodbrequiredRuntime dependency for MongoDB driver

Agent activity

7 hits · last 30 days

node

Resources

githubgit://github.com/debitoor/mongopatch ↗

packagemongopatch ↗

homepagehttps://github.com/debitoor/mongopatch#readme ↗