Skip to content

Commit 60c3fd2

Browse files
author
Dave
authored
DOCSP-18980 improve mongoshrc visibility (#179)
* DOCSP-18980 improve visibility of mongoshrc * DOCSP-18980 * Move to include * better config file reference naming * Add examples * Review feedback * Typo * Update example * Typo
1 parent ccb4d32 commit 60c3fd2

8 files changed

+176
-79
lines changed

‎source/includes/examples/ex-display-dbname-and-hostname.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
To display the database and hostname in the :binary:`~bin.mongosh`
2+
prompt, use a function like this one:
3+
4+
.. code-block:: javascript
5+
6+
{
7+
const hostnameSymbol = Symbol('hostname');
8+
prompt = () => {
9+
if (!db[hostnameSymbol])
10+
db[hostnameSymbol] = db.serverStatus().host;
11+
return `${db.getName()}@${db[hostnameSymbol]}> `;
12+
};
13+
}
14+
15+
The prompt will look like this:
16+
17+
.. code-block:: javascript
18+
19+
admin@centos0722:27502>
20+

‎source/includes/examples/ex-display-line-numbers.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
This code will dynamically update the :binary:`~bin.mongosh` prompt
2+
to display line numbers:
3+
4+
.. code-block:: javascript
5+
6+
let cmdCount = 1;
7+
prompt = function() {
8+
return (cmdCount++) + "> ";
9+
}
10+
11+
The prompt will look like this:
12+
13+
.. code-block:: javascript
14+
15+
1> show collections
16+
2> use test
17+
3>
18+

‎source/includes/examples/ex-display-system-uptime.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
To create a prompt that shows the system uptime and a count of
2+
documents across all collections in the current database, use a
3+
function like this one:
4+
5+
.. code-block:: javascript
6+
7+
8+
prompt = function() {
9+
return "Uptime:" + db.serverStatus().uptime +
10+
" Documents:" + db.stats().objects +
11+
" > ";
12+
}
13+

‎source/includes/fact-mongoshrc-loading.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
On startup, :binary:`mongosh` checks the user's ``HOME`` directory for
2+
a JavaScript file named :ref:`.mongoshrc.js <mongoshrc-js>`. If this
3+
file is found, :binary:`mongosh` reads the content of
4+
:ref:`.mongoshrc.js <mongoshrc-js>` before displaying the prompt for
5+
the first time.
6+
7+
If you use :binary:`mongosh` to evaluate a JavaScript file or
8+
expression, either by using the :option:`--eval <mongosh --eval>`
9+
option on the command line or by specifying a :ref:`.js file
10+
<mdb-shell-execute-file>`, :binary:`mongosh` reads :ref:`.mongoshrc.js
11+
<mongoshrc-js>` *after* the JavaScript has finished processing. You can
12+
prevent :ref:`.mongoshrc.js <mongoshrc-js>` from being loaded by using
13+
the :option:`--norc <mongosh --norc>` option.
14+
15+
.. note::
16+
17+
The legacy :binary:`~bin.mongo` shell used a configuation file
18+
called ``.mongorc.js``. If :binary:`mongosh` detects this file on
19+
startup, and :ref:`.mongoshrc.js <mongoshrc-js>` is not present,
20+
:binary:`mongosh` will suggest renaming ``.mongorc.js`` to
21+
:ref:`.mongoshrc.js <mongoshrc-js>`.
22+
23+
The legacy ``.mongorc.js`` file is not loaded.
24+

‎source/mongoshrc.txt‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _mongoshrc-js:
2+
3+
=================================
4+
``.mongoshrc`` Configuration File
5+
=================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
..
16+
COMMENT This file might be expanded later. For now the content is
17+
same here and in run-commands.
18+
19+
.. include:: /includes/fact-mongoshrc-loading.rst
20+
21+
Examples
22+
--------
23+
24+
The following examples create custom prompts. To display:
25+
26+
- :ref:`line numbers <ex-display-line-numbers>`
27+
- :ref:`database and hostname <ex-display-dbname-and-hostname>`
28+
- :ref:`system uptime and document count <ex-display-system-up-time>`
29+
30+
add the example code to :ref:`.mongoshrc.js <mongoshrc-js>`.
31+
32+
.. _ex-display-line-numbers:
33+
34+
Display Line Numbers
35+
~~~~~~~~~~~~~~~~~~~~
36+
37+
.. include:: /includes/examples/ex-display-line-numbers.rst
38+
39+
.. _ex-display-dbname-and-hostname:
40+
41+
Display Database and Hostname
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
.. include:: /includes/examples/ex-display-dbname-and-hostname.rst
45+
46+
.. _ex-display-system-up-time:
47+
48+
Display System Up Time and Document Count
49+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50+
51+
.. include:: /includes/examples/ex-display-system-uptime.rst
52+

‎source/reference/configure-shell-settings.txt‎

Lines changed: 3 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -148,69 +148,17 @@ to set the prompt each time you start up :binary:`~bin.mongosh`.
148148
Display Line Numbers
149149
~~~~~~~~~~~~~~~~~~~~
150150

151-
This code will dynamically update the :binary:`~bin.mongosh` prompt
152-
to display line numbers:
153-
154-
.. code-block:: javascript
155-
156-
let cmdCount = 1;
157-
prompt = function() {
158-
return (cmdCount++) + "> ";
159-
}
160-
161-
The prompt will look like this:
162-
163-
.. code-block:: javascript
164-
165-
1> show collections
166-
2> use test
167-
3>
151+
.. include:: /includes/examples/ex-display-line-numbers.rst
168152

169153
Display Database and Hostname
170154
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
171155

172-
Use a function like this one to display the database and hostname in
173-
the :binary:`~bin.mongosh` prompt:
174-
175-
.. code-block:: javascript
176-
177-
{
178-
const hostnameSymbol = Symbol('hostname');
179-
prompt = () => {
180-
if (!db[hostnameSymbol])
181-
db[hostnameSymbol] = db.serverStatus().host;
182-
return `${db.getName()}@${db[hostnameSymbol]}> `;
183-
};
184-
}
185-
186-
The prompt will look like this:
187-
188-
.. code-block:: javascript
189-
190-
admin@centos0722:27502>
156+
.. include:: /includes/examples/ex-display-dbname-and-hostname.rst
191157

192158
Display System Up Time and Document Count
193159
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194160

195-
Use a function like this one for a prompt that shows the system uptime
196-
and a count of documents across all collections in the current
197-
database.
198-
199-
.. code-block:: javascript
200-
201-
202-
prompt = function() {
203-
return "Uptime:" + db.serverStatus().uptime +
204-
" Documents:" + db.stats().objects +
205-
" > ";
206-
}
207-
208-
209-
The prompt will look like this:
210-
211-
.. code-block:: javascript
212-
213-
Uptime:451563 Documents:58 >
161+
.. include:: /includes/examples/ex-display-system-uptime.rst
214162

215163
Behavior
216164
--------

‎source/run-commands.txt‎

Lines changed: 3 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -86,33 +86,10 @@ For more documentation of basic MongoDB operations in ``mongosh``, see:
8686
- :doc:`/crud/delete`
8787
- :doc:`/reference/methods`
8888

89-
.. _mongoshrc-js:
90-
9189
``.mongoshrc.js`` File
9290
----------------------
9391

94-
On startup, ``mongosh`` checks the user's ``HOME`` directory for a
95-
JavaScript file named ``.mongoshrc.js``. If this file is found,
96-
``mongosh`` interprets the content of ``.mongoshrc.js`` before
97-
displaying the prompt for the first time.
98-
99-
If you use the shell to evaluate a JavaScript file or expression,
100-
either by using the :option:`--eval <mongosh --eval>` option on the
101-
command line or by specifying
102-
:ref:`a .js file to mongosh <mdb-shell-execute-file>`, ``mongosh``
103-
reads the ``.mongoshrc.js`` file *after* the JavaScript has finished
104-
processing. You can prevent ``.mongoshrc.js`` from being loaded by
105-
using the :option:`--norc <mongosh --norc>` option.
106-
107-
.. note::
108-
109-
The legacy :binary:`~bin.mongo` shell used a configuation file
110-
called ``.mongorc.js``. If ``mongosh`` detects this file on startup,
111-
and ``.mongoshrc.js`` is not present, ``mongosh`` will suggest
112-
renaming ``.mongorc.js`` to ``.mongoshrc.js``.
113-
114-
The legacy ``.mongorc.js`` file will not be loaded.
115-
92+
.. include:: /includes/fact-mongoshrc-loading.rst
11693

11794
Terminate a Running Command
11895
---------------------------
@@ -167,4 +144,6 @@ with ``Ctrl + L`` and ``console.clear()``.
167144

168145
/crud
169146
/run-agg-pipelines
147+
/mongoshrc
170148
/telemetry
149+

‎source/write-scripts.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -434,6 +434,49 @@ The following lines are equivalent.
434434
space it will not be saved in your command history. This minimizes
435435
exposure if you enter passwords on the command line.
436436

437+
Execute Code From a Configuration File
438+
--------------------------------------
439+
440+
On startup, :binary:`mongosh` checks for a file named
441+
:ref:`.mongoshrc.js <mongoshrc-js>`. If :ref:`.mongoshrc.js
442+
<mongoshrc-js>` is found, :binary:`mongosh` interprets the file before
443+
displaying the prompt for the first time.
444+
445+
.. seealso::
446+
447+
:ref:`.mongoshrc.js <mongoshrc-js>`, :ref:`mongosh-shell-settings`
448+
449+
Execute JavaScript Code
450+
~~~~~~~~~~~~~~~~~~~~~~~
451+
452+
.. include:: /includes/examples/ex-display-line-numbers.rst
453+
454+
Execute MongoDB Code
455+
~~~~~~~~~~~~~~~~~~~~
456+
457+
To create a log of when your :binary:`mongosh` client connects to a
458+
database, add the following to ``<your-home-directory>/.mongoshrc.js``:
459+
460+
.. code-block:: javascript
461+
462+
db.clientConnections.insertOne( { connectTime: ISODate() } )
463+
464+
Each time you connect to a database, the MongoDB server adds a
465+
document like the following to the ``clientConnections`` collection.
466+
467+
.. code-block:: javascript
468+
:copyable: false
469+
470+
{
471+
_id: ObjectId("61d4bbf0fa4c85f53418070f"),
472+
connectTime: ISODate("2022-01-04T21:28:16.367Z")
473+
}
474+
475+
Execute JavaScript and MongoDB Code
476+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
477+
478+
.. include:: /includes/examples/ex-display-dbname-and-hostname.rst
479+
437480
.. toctree::
438481
:titlesonly:
439482

0 commit comments

Comments
 (0)