Provide limited module support for the mongo shell. Includes three sample modules - assert, path and harness.
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Mongo Modules


Mongo's shell can be very helpful for batch processing data. While it's not fast and not event drive it is terribly convenient (e.g. it comes with Mongo, nothing else needs to be installed). Why not leverage it? What is missing is a basic module system. Thats where mongo-modules.js comes in.

mongo-modules.js provides a minimal module system for Mongo's shell. You include it in your .mongorc.js file. Here's an example .mongorc.js file:

	// Set up some useful environment like variables
	HOME="/home/" + USERNAME
	// Now We're ready to load the modules bootstrap.
	load(MONGO_MODULES[0] + "/mongo-modules.js");

If you wanted to load the path module you might do something like-

	// Path is a simple example module based on NodeJS path's module
	path = require("path");
	// Now you can do things like path.join()
	// joining HOME and myproject should yield a path
	// like /home/johndoe/myproject based on the settings
	// in the .mongorc.js file above.
	console.log(path.join(HOME, "myproject"));


The .mongorc.js file is a file looked for by the mongo shell. It goes you your home directory (e.g. if your username was johndoe you home directory might be /Users/johndoe or /home/johndoe depending on the flavor of Unix your using).


Mongo modules don't support directories as modules like NodeJS. This is because parsing package.json is problematic from the shell (e.g. no JSON.parse(), no eval). If you want to use directory based modules then bootstrap the parts by including an index.js file. Hopefully I'll figure out a remedy for this and use a proper package.json file instead.

mongo-modules.js's basic services

  • console.log(), console.error() - mapped to print()
  • require() - load a module

Three demonstration modules come with mongo-modules.js - assert, path and harness. Loading each can be done after installation. E.g. from the mongo shell do the following commands.

	assert = require("assert");
	path = require("path");
	harness = require("harness");

If you would like to try the test programs then you need to first load the .mongorc.js file then run the test script. Here's and example-

	# Load the .mongorc.js file, then load harness_test.js
	mongo ~/.mongorc.js harness_test.js

The output should look something like-

	MongoDB shell version: 2.2.0
	connecting to: test
	loading file: /home/johndoe/.mongorc.js
	loading file: harness_test.js
	Starting [harness_test.js] ...
		Starting Testing push() ...
			Testing push() called
			Testing push() OK
	harness_test.js Success!


Modify your .mongorc.js file to define the MONGO_MODULES array. The array should contain one or more paths to search for modules. It should include as the first entry the location of where you've mongo-modules.js. It also invoke mongo-modules.js via a load statement.

	MONGO_MODULES=["/home/johndoe/mongo-modules", PWD];
	load(MONGO_MODULES[0] + "/mongo-modules.js");

Now the next time you launch the Mongo shell it should load mongo-modules.js and support the console.log() and console.error() commands.