From d1af11cee016c9a286fca185910bfc16938a83c5 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Mon, 1 Oct 2012 12:44:59 -0400 Subject: [PATCH 1/2] DOCS-527 edit, reformat, add dbshell and environment variables --- source/reference/mongo.txt | 122 +++++++++++++++++++++++++++++-------- 1 file changed, 96 insertions(+), 26 deletions(-) diff --git a/source/reference/mongo.txt b/source/reference/mongo.txt index d2e3fd8b02c..7c7726bd9c0 100644 --- a/source/reference/mongo.txt +++ b/source/reference/mongo.txt @@ -1,20 +1,29 @@ .. _mongo: +.. meta:: + :description: The mongo shell man page + :keywords: man page, mongo, javascript, shell + .. default-domain:: mongodb ================ -:program:`mongo` +mongo ================ Synopsis -------- +.. describe:: mongo [--shell] [--nodb] [--norc] [--quiet] [--port ] [--host ] [--eval ] [-u ] [--username ] [-p ] [--password ] [--help] [-h] [--version] [--verbose] [--ipv6] [database] [file.js] + +Description +----------- + :program:`mongo` is an interactive JavaScript shell interface to -MongoDB. :program:`mongo` provides a powerful administrative interface -for systems administrators as well as an way to test queries and +MongoDB. :program:`mongo` provides a powerful interface +for systems administrators as well as a way to test queries and operations directly with the database. To increase the flexibility of :program:`mongo`, the shell provides a fully functional JavaScript -environment. This manual page, addresses the basic invocation of the +environment. This document addresses the basic invocation of the :program:`mongo` shell and an overview of its usage. .. STUB -- This manual contains more extensive documentation of :program:`mongo` in the ":doc:`/mongo`" document. @@ -26,84 +35,84 @@ Options .. program:: mongo -.. option:: --shell +.. cmdoption:: --shell If you invoke the :program:`mongo` and specify a :term:`JavaScript` file as an argument, or ":option:`mongo --eval`" the - :option:`--shell` provides the user with a shell prompt after the + :option:`--shell` option provides the user with a shell prompt after the file finishes executing. -.. option:: --nodb +.. cmdoption:: --nodb Use this option to prevent the shell from connecting to any database instance. -.. option:: --norc +.. cmdoption:: --norc By default :program:`mongo` runs the ``~/.mongorc.js`` file when it starts. Use this option to prevent the shell from sourcing this file on start up. -.. option:: --quiet +.. cmdoption:: --quiet Silences output from the shell during the connection process. -.. option:: --port +.. cmdoption:: --port Specify the port where the :program:`mongod` or :program:`mongos` instance is listening. Unless specified :program:`mongo` connects to :program:`mongod` instances on port 27017, which is the default :program:`mongod` port. -.. option:: --host +.. cmdoption:: --host Specific the host where the :program:`mongod` or :program:`mongos` is running to connect to as ````. By default :program:`mongo` will attempt to connect to MongoDB process running on the localhost. -.. option:: --eval +.. cmdoption:: --eval Evaluates a JavaScript specified as an argument to this option. :program:`mongo` does not load its own environment when evaluating - code: as a result many convinces of the shell environment are not + code: as a result many options of the shell environment are not available. -.. option:: --username , -u +.. cmdoption:: --username , -u Specify a username to authenticate to the MongoDB instance, if your database requires authentication. Use in conjunction with the :option:`mongo --password` option to supply a password. -.. option:: --password , -p +.. cmdoption:: --password , -p Specify a password to authenticate to the MongoDB instance, if your database requires authentication. Use in conjunction with the :option:`mongo --username` option to supply a username. If you specify a :option:`--username ` without the - :option:`--password` option, :program:`mongo` will prompt for a + :option:`mongo --password` option, :program:`mongo` will prompt for a password interactively. -.. option:: --help, -h +.. cmdoption:: --help, -h Returns a basic help and usage text. -.. option:: --version +.. cmdoption:: --version Returns the version of the shell. -.. option:: --verbose +.. cmdoption:: --verbose Increases the verbosity of the output of the shell during the connection process. -.. option:: --ipv6 +.. cmdoption:: --ipv6 Enables IPv6 support that allows :program:`mongo` to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes, including :program:`mongo`, disable IPv6 support by default. -.. option:: +.. cmdoption:: Specify the "database address" of the database to connect to. For example: :: @@ -122,15 +131,13 @@ Options .. _mongo-shell-file: -.. option:: +.. cmdoption:: Optionally, specify a JavaScript file as the final argument to the shell. The shell will run the file and then exit. Use the - :option:`mongo --shell` to return to a shell after the file + :option:`mongo --shell` option to return to a shell after the file finishes running. - This should be the last address - Usage ----- @@ -156,7 +163,7 @@ values for your situation and substitute or omit the :option:`--port` as needed. To execute a JavaScript file without evaluating the ``~/.mongorc.js`` -file before starting a sell session, use the following form: +file before starting a shell session, use the following form: .. code-block:: sh @@ -172,3 +179,66 @@ the :option:`--eval ` option, use the following form: Note the use of single quotes (e.g. ``'``) to enclose the JavaScript, as well as the additional JavaScript required to generate this output. + +Files +----- + +:file:`~/.dbshell` + + :program:`mongo` maintains a history of commands in the `.dbshell` + file. + + .. note: + + Authentication commands (such as :dbcommand:`authenticate`, + :method:`db.addUser()`) will not be saved in the history file. + + .. warning: + + Versions of Windows :command:`mongo.exe` earlier than 2.2.0 + will save the `.dbshell` file in the :command:`mongo.exe` + working directory. + +:file:`~/.mongorc.js` + + :program:`mongo` will read `.mongorc.js` from the home directory + of the user invoking :program:`mongo`. + Specify the :option:`mongo --norc` option to disable + reading `.mongorc.js`. + +:file:`/tmp/mongo_edit{}.js` + + Created by :program:`mongo` when editing a file. If the file + exists :program:`mongo` will append an integer from 1 to 10 to + the time value to attempt to create a unique file. + +:file:`%TEMP%\mongo_edit{}.js` + + Created by :command:`mongo.exe` on Windows when editing a file. + If the file + exists :program:`mongo` will append an integer from 1 to 10 to + the time value to attempt to create a unique file. + +Environment +----------- + +.. envvar:: EDITOR + + Specify the path to an editor to use with the `edit` shell command. + A JavaScript variable `EDITOR` will override the value of + :envvar:`EDITOR`. + +.. envvar:: HOME + + Specify the path to the home directory where `.mongorc.js` will be + read from and `.dbshell` will be written to. + +.. envvar:: HOMEDRIVE + + Specify the Windows path to the home directory where `.mongorc.js` will be + read from and `.dbshell` will be written to. + +.. envvar:: HOMEPATH + + Specify the Windows path to the home directory where `.mongorc.js` will be + read from and `.dbshell` will be written to. From 07127331d1f86994f85bba2da699744a8cb38d2d Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Mon, 1 Oct 2012 14:12:35 -0400 Subject: [PATCH 2/2] DOCS-527 clean up formatting --- source/reference/mongo.txt | 83 ++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/source/reference/mongo.txt b/source/reference/mongo.txt index 7c7726bd9c0..6ff7fe63982 100644 --- a/source/reference/mongo.txt +++ b/source/reference/mongo.txt @@ -1,14 +1,15 @@ -.. _mongo: - -.. meta:: - :description: The mongo shell man page - :keywords: man page, mongo, javascript, shell - -.. default-domain:: mongodb - ================ mongo ================ +.. only:: html + + .. meta:: + :description: The mongo command man page. + :keywords: mongo, mongodb, man page, mongo process, mongo shell + +.. default-domain:: mongodb + +.. _mongo: Synopsis -------- @@ -19,10 +20,10 @@ Description ----------- :program:`mongo` is an interactive JavaScript shell interface to -MongoDB. :program:`mongo` provides a powerful interface +MongoDB. The :program:`mongo` command provides a powerful interface for systems administrators as well as a way to test queries and operations directly with the database. To increase the flexibility of -:program:`mongo`, the shell provides a fully functional JavaScript +the :program:`mongo` command, the shell provides a fully functional JavaScript environment. This document addresses the basic invocation of the :program:`mongo` shell and an overview of its usage. @@ -37,60 +38,63 @@ Options .. cmdoption:: --shell - If you invoke the :program:`mongo` and specify a :term:`JavaScript` - file as an argument, or ":option:`mongo --eval`" the - :option:`--shell` option provides the user with a shell prompt after the - file finishes executing. + Enables the shell interface after a :term:`JavaScript` file is evaluated. + If you invoke the :program:`mongo` command and specify a JavaScript + file as an argument, or use :option:`mongo --eval` to specify + JavaScript on the command line, the :option:`mongo --shell` option + provides the user with a shell prompt after the file finishes + executing. .. cmdoption:: --nodb - Use this option to prevent the shell from connecting to any - database instance. + Prevents the shell from connecting to any database instances. .. cmdoption:: --norc - By default :program:`mongo` runs the ``~/.mongorc.js`` file when it - starts. Use this option to prevent the shell from sourcing this - file on start up. - + Prevents the shell from sourcing and evaluating + :file:`~/.mongorc.js` on startup. + .. cmdoption:: --quiet Silences output from the shell during the connection process. .. cmdoption:: --port - Specify the port where the :program:`mongod` or :program:`mongos` + Specifies the port where the :program:`mongod` or :program:`mongos` instance is listening. Unless specified :program:`mongo` connects to :program:`mongod` instances on port 27017, which is the default :program:`mongod` port. .. cmdoption:: --host - Specific the host where the :program:`mongod` or :program:`mongos` is running to + specifies the host where the :program:`mongod` or :program:`mongos` is running to connect to as ````. By default :program:`mongo` will attempt - to connect to MongoDB process running on the localhost. + to connect to a MongoDB process running on the localhost. .. cmdoption:: --eval - Evaluates a JavaScript specified as an argument to this + Evaluates a JavaScript expression specified as an argument to this option. :program:`mongo` does not load its own environment when evaluating code: as a result many options of the shell environment are not available. .. cmdoption:: --username , -u - Specify a username to authenticate to the MongoDB instance, if your - database requires authentication. Use in conjunction with the + Specifies a username to authenticate to the MongoDB instance. + Use in conjunction with the :option:`mongo --password` option to supply a password. + If you specify a username and password but the default database + or the specified database do not require authentication, + :program:`mongo` will exit with an exception. .. cmdoption:: --password , -p - Specify a password to authenticate to the MongoDB instance, if your - database requires authentication. Use in conjunction with the + Specifies a password to authenticate to the MongoDB instance. + Use in conjunction with the :option:`mongo --username` option to supply a username. If you specify a :option:`--username ` without the :option:`mongo --password` option, :program:`mongo` will prompt for a - password interactively. + password interactively if authentication is required. .. cmdoption:: --help, -h @@ -114,7 +118,7 @@ Options .. cmdoption:: - Specify the "database address" of the database to connect to. For + Specifies the "database address" of the database to connect to. For example: :: mongo admin @@ -133,8 +137,9 @@ Options .. cmdoption:: - Optionally, specify a JavaScript file as the final argument to the - shell. The shell will run the file and then exit. Use the + Specifies a JavaScript file to run and then exit. + Must be the last option specified. + Use the :option:`mongo --shell` option to return to a shell after the file finishes running. @@ -224,21 +229,21 @@ Environment .. envvar:: EDITOR - Specify the path to an editor to use with the `edit` shell command. + Specifies the path to an editor to use with the `edit` shell command. A JavaScript variable `EDITOR` will override the value of :envvar:`EDITOR`. .. envvar:: HOME - Specify the path to the home directory where `.mongorc.js` will be - read from and `.dbshell` will be written to. + specifies the path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to. .. envvar:: HOMEDRIVE - Specify the Windows path to the home directory where `.mongorc.js` will be - read from and `.dbshell` will be written to. + specifies the Windows path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to. .. envvar:: HOMEPATH - Specify the Windows path to the home directory where `.mongorc.js` will be - read from and `.dbshell` will be written to. + specifies the Windows path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to.