Skip to content

Commit 1cef352

Browse files
jwilliams-mongojwilliams-mongo
authored
(DOCSP-10991): add Mongo() and scripting docs (mongodb#24)
* (DOCSP-10991): add Mongo() and scripting docs * (DOCSP-10991): copy review feedback * (DOCSP-10991): fix connect() links * (DOCSP-10991): copy review pt 2 * (DOCSP-10991): tech review feedback * (DOCSP-10991): remove duplicate 'mdb-shell' definition
1 parent 13933dd commit 1cef352

File tree

6 files changed

+241
-2
lines changed

6 files changed

+241
-2
lines changed

‎snooty.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ intersphinx = ["https://docs.mongodb.com/manual/objects.inv"]
66
toc_landing_pages = ["/crud"]
77

88
[constants]
9-
mdb-shell = "The MongoDB Shell"
109

1110
[substitutions]
1211

‎source/connect.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,16 @@ For ``tls`` connections:
204204

205205
mongosh "mongodb://mongodb0.example.com:28015" --tls
206206

207+
Connect to a Different Deployment
208+
---------------------------------
209+
210+
You can use the :method:`Mongo()` or the :manual:`connect()
211+
</reference/method/connect/>` methods to connect to a different MongoDB
212+
deployment from within the |mdb-shell|.
213+
214+
To learn how to connect to a different deployment using these methods,
215+
see :ref:`mdb-shell-open-new-connections-in-shell`.
216+
207217
Disconnect from a Deployment
208218
----------------------------
209219

‎source/includes/admonitions/note-redact-credentials-command-history.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. note::
2+
3+
The |mdb-shell| redacts credentials from the :ref:`command history
4+
<mdb-shell-command-history>` and the :ref:`logs
5+
<mdb-shell-view-logs>`.

‎source/index.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,10 @@ Learn More
106106

107107
- :ref:`Run Aggregation Pipelines <mdb-shell-aggregation>`
108108

109+
- :ref:`Write Scripts <mdb-shell-write-scripts>`
110+
111+
- :ref:`Retrieve Logs <mdb-shell-logs>`
112+
109113
- :ref:`View Available Methods in the MongoDB Shell <mdb-shell-methods>`
110114

111115
.. class:: hidden
@@ -117,5 +121,6 @@ Learn More
117121
/connect
118122
/crud
119123
/run-agg-pipelines
124+
/write-scripts
120125
/logs
121126
/reference

‎source/logs.txt

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,19 @@ Retrieve MongoDB Shell Logs
1919
<https://github.com/pinojs/pino>`__.
2020

2121
You can view or tail the logs for a |mdb-shell| session based on its
22-
session ID.
22+
session ID.
23+
24+
.. include:: /includes/admonitions/note-redact-credentials-command-history.rst
25+
26+
.. _mdb-shell-view-logs:
2327

2428
View |mdb-shell| Logs
2529
---------------------
2630

2731
.. include:: /includes/steps/view-logs.rst
2832

33+
.. _mdb-shell-command-history:
34+
2935
View |mdb-shell| Command History
3036
--------------------------------
3137

‎source/write-scripts.txt

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
.. _mdb-shell-write-scripts:
2+
3+
=================================
4+
Write Scripts for the |mdb-shell|
5+
=================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
You can write scripts for the |mdb-shell| that manipulate data in
16+
MongoDB or perform administrative operations.
17+
18+
This tutorial introduces using the |mdb-shell| with JavaScript to
19+
access MongoDB.
20+
21+
.. _mdb-shell-open-new-connections-in-shell:
22+
23+
Open a New Connection
24+
---------------------
25+
26+
From the |mdb-shell| or from a JavaScript file, you can instantiate
27+
database connections using the :method:`Mongo()` method:
28+
29+
.. code-block:: javascript
30+
:copyable: false
31+
32+
new Mongo()
33+
new Mongo(<host>)
34+
new Mongo(<host:port>)
35+
36+
.. note::
37+
38+
The |mdb-shell| does not support the
39+
:manual:`ClientSideFieldLevelEncryptionOptions
40+
</reference/method/Mongo/#clientsidefieldlevelencryptionoptions>`
41+
document with the :method:`Mongo()` method.
42+
43+
Consider a MongoDB instance running on localhost on the default port.
44+
45+
.. example::
46+
47+
The following example:
48+
49+
- Instantiates a new connection to the instance, and
50+
- Sets the global ``db`` variable to ``myDatabase`` using the
51+
:method:`getDB()` method.
52+
53+
.. code-block:: javascript
54+
55+
conn = Mongo();
56+
db = conn.getDB("myDatabase");
57+
58+
If you connect to a MongoDB instance that enforces access control, you
59+
must include the credentials in the :manual:`connection string
60+
</reference/connection-string/>`.
61+
62+
.. example::
63+
64+
The following command connects to a MongoDB instance that is:
65+
66+
- Running on ``localhost`` on the default port, and
67+
- Secured using :manual:`SCRAM </core/security-scram/>`.
68+
69+
.. code-block:: javascript
70+
71+
conn = Mongo("mongodb://<username>:<password>@localhost:27017/<authDB>");
72+
73+
.. the manual page says to use db.auth(), which isn't implemented yet.
74+
this is the only way I could get it to work.
75+
https://docs.mongodb.com/manual/tutorial/write-scripts-for-the-mongo-shell/#opening-new-connections
76+
77+
.. include:: /includes/admonitions/note-redact-credentials-command-history.rst
78+
79+
Additionally, you can use the :manual:`connect()
80+
</reference/method/connect/>` method to connect to the MongoDB instance.
81+
82+
.. example::
83+
84+
The following command:
85+
86+
- Connects to the MongoDB instance that is running on ``localhost`` with
87+
the non-default port ``27020``, and
88+
- Sets the global ``db`` variable.
89+
90+
.. code-block:: javascript
91+
92+
db = connect("localhost:27020/myDatabase");
93+
94+
.. skipping the Differences Between Interactive and Scripted mongo
95+
section as most of the javascript equivalents to the shell helpers
96+
have not yet been implemented in mongosh -- revisit later
97+
https://docs.mongodb.com/manual/tutorial/write-scripts-for-the-mongo-shell/#differences-between-interactive-and-scripted-mongo
98+
99+
.. also skippping --eval section as I'm having issues getting it to work
100+
https://docs.mongodb.com/manual/tutorial/write-scripts-for-the-mongo-shell/#eval-option
101+
102+
Use ``require()`` to Include External Files and Modules
103+
-------------------------------------------------------
104+
105+
.. important::
106+
107+
A complete description of Node.js, modules, and the
108+
`require() <https://nodejs.org/api/modules.html#modules_require_id>`__
109+
function is out of scope for this tutorial. To learn more, refer to
110+
the `Node.js Documentation <https://nodejs.org/api/modules.html>`__.
111+
112+
You can use the `require()
113+
<https://nodejs.org/api/modules.html#modules_require_id>`__ function in
114+
the |mdb-shell| to include modules which exist in separate files.
115+
116+
Require a File
117+
~~~~~~~~~~~~~~
118+
119+
You can ``require()`` JavaScript files in the |mdb-shell| without any
120+
additional setup or configuration.
121+
122+
.. note::
123+
124+
The |mdb-shell| does not execute files imported with ``require()``.
125+
The |mdb-shell| adds everything from an imported file to the current
126+
execution scope.
127+
128+
.. example::
129+
130+
Use one of the following commands include a file from the current
131+
working directory named ``tests.js``:
132+
133+
.. code-block:: javascript
134+
135+
require('./tests.js')
136+
137+
.. code-block:: javascript
138+
139+
var tests = require('./tests.js')
140+
141+
Require a Native Module
142+
~~~~~~~~~~~~~~~~~~~~~~~
143+
144+
You can ``require()`` native Node modules (such as
145+
`fs <https://nodejs.org/api/fs.html#fs_file_system>`__) in the
146+
|mdb-shell| without any additional setup or configuration.
147+
148+
.. example::
149+
150+
Use one of the following commands to include the ``fs`` module:
151+
152+
.. code-block:: javascript
153+
154+
require('fs')
155+
156+
.. code-block:: javascript
157+
158+
var fs = require('fs');
159+
160+
Require a Non-Native Module
161+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
162+
163+
To ``require()`` non-native Node modules (such as those downloaded from
164+
`npm <https://www.npmjs.com/>`__) you must install the module globally
165+
or to the ``node_modules`` directory in your current working directory.
166+
167+
Once you install or copy your desired package to one of the module
168+
directories, you can ``require()`` that package.
169+
170+
.. example::
171+
172+
Use one of the following commands to include the
173+
`moment <https://www.npmjs.com/package/moment>`__:
174+
175+
.. code-block:: javascript
176+
177+
require('moment')
178+
179+
.. code-block:: javascript
180+
181+
var moment = require('moment')
182+
183+
.. _mdb-shell-execute-file:
184+
185+
Execute a JavaScript File
186+
-------------------------
187+
188+
You can execute a ``.js`` file from within the |mdb-shell|
189+
using the ``.load`` command.
190+
191+
.. example::
192+
193+
The following command loads and executes the ``myjstest.js`` file:
194+
195+
.. code-block:: javascript
196+
197+
.load myjstest.js
198+
199+
The ``.load`` command accepts relative and absolute paths. If the
200+
current working directory of the |mdb-shell| is ``/data/db``,
201+
and ``myjstest.js`` resides in the ``/data/db/scripts`` directory, then
202+
the following calls within the |mdb-shell| are equivalent:
203+
204+
.. code-block:: javascript
205+
:copyable: false
206+
207+
.load scripts/myjstest.js
208+
.load /data/db/scripts/myjstest.js
209+
210+
.. note::
211+
212+
There is no search path for the ``.load`` command. If the desired
213+
script is not in the current working directory or the full specified
214+
path, the |mdb-shell| cannot access the file.

0 commit comments

Comments
 (0)