Fetching contributors…
Cannot retrieve contributors at this time
152 lines (105 sloc) 4.71 KB
Write Scripts for the ``mongo`` Shell
.. default-domain:: mongodb
.. contents:: On this page
:backlinks: none
:depth: 1
:class: singlecol
You can write scripts for the :program:`mongo` shell in JavaScript that
manipulate data in MongoDB or perform administrative operation. For
more information about the :program:`mongo` shell, see the
:ref:`running-js-scripts-in-mongo-on-mongod-host` section for more
information about using these :program:`mongo` script.
This tutorial provides an introduction to writing JavaScript that uses
the :program:`mongo` shell to access MongoDB.
.. _mongo-shell-new-connections:
Opening New Connections
From the :program:`mongo` shell or from a JavaScript file, you can
instantiate database connections using the :method:`Mongo()`
.. code-block:: javascript
new Mongo()
new Mongo(<host>)
new Mongo(<host:port>)
Consider the following example that instantiates a new connection to
the MongoDB instance running on localhost on the default port and sets
the global ``db`` variable to ``myDatabase`` using the
:method:`~Mongo.getDB()` method:
.. code-block:: javascript
conn = new Mongo();
db = conn.getDB("myDatabase");
If connecting to a MongoDB instance that enforces access control,
you can use the :method:`db.auth()` method to authenticate.
Additionally, you can use the :method:`connect()` method
to connect to the MongoDB instance. The following example connects to
the MongoDB instance that is running on ``localhost`` with the
non-default port ``27020`` and set the global ``db`` variable:
.. code-block:: javascript
db = connect("localhost:27020/myDatabase");
.. seealso:: :doc:`/reference/method/`
Differences Between Interactive and Scripted ``mongo``
When writing scripts for the :program:`mongo` shell, consider the
- To set the ``db`` global variable, use the :method:`~Mongo.getDB()`
method or the :method:`connect()` method. You can assign the database
reference to a variable other than ``db``.
- Write operations in the :program:`mongo` shell use a write concern of
:ref:`{ w: 1 } <wc-w>` by default. If performing bulk operations, use
the :method:`Bulk()` methods. See
:ref:`write-methods-incompatibility` for more information.
.. versionchanged:: 2.6
Before MongoDB 2.6, call :method:`db.getLastError()` explicitly to
wait for the result of :doc:`write operations
- You **cannot** use any shell helper (e.g. ``use <dbname>``, ``show
dbs``, etc.) inside the JavaScript file because they are not valid
The following table maps the most common :program:`mongo` shell
helpers to their JavaScript equivalents.
.. include:: /includes/table/helpers-to-javascript.rst
- In interactive mode, :program:`mongo` prints the results of
operations including the content of all cursors. In scripts, either
use the JavaScript ``print()`` function or the :program:`mongo`
specific ``printjson()`` function which returns formatted JSON.
.. example::
To print all items in a result cursor in :program:`mongo` shell
scripts, use the following idiom:
.. code-block:: javascript
cursor = db.collection.find();
while ( cursor.hasNext() ) {
printjson( );
.. _mongo-shell-scripting:
From the system prompt, use :program:`mongo` to evaluate JavaScript.
``--eval`` option
Use the :option:`--eval <mongo --eval>` option to :program:`mongo` to
pass the shell a JavaScript fragment, as in the following:
.. code-block:: sh
mongo test --eval "printjson(db.getCollectionNames())"
This returns the output of :method:`db.getCollectionNames()` using the
:program:`mongo` shell connected to the :program:`mongod` or
:program:`mongos` instance running on port ``27017`` on the
``localhost`` interface.
.. _mongo-shell-javascript-file:
Execute a JavaScript file
You can specify a ``.js`` file to the :program:`mongo` shell, and
:program:`mongo` will execute the JavaScript directly. Consider the
following example:
.. code-block:: sh
mongo localhost:27017/test myjsfile.js
This operation executes the ``myjsfile.js`` script in a
:program:`mongo` shell that connects to the ``test`` :term:`database`
on the :program:`mongod` instance accessible via the ``localhost``
interface on port ``27017``.
Alternately, you can specify the mongodb connection parameters inside
of the javascript file using the ``Mongo()`` constructor. See
:ref:`mongo-shell-new-connections` for more information.
.. include:: /includes/fact-execute-javascript-from-shell.rst