Skip to content

Commit 52ca527

Browse files
jeff-allen-mongojeff-allen-mongo
committed
(DOCSP-25554): Export favorite connections with the CLI (#431)
* (DOCSP-25219): Import and export favorite connections with the CLI * fix snooty.toml * (DOCSP-25219): Export favorite connections with the CLI * update snooty.toml * typo * WIP * edits * more edits * edits * comma splice * updates per Dave's review * edits * edits * wording * wording * tweak admonition * edits * tweaks for consistency * WIP * update export page per tech review * edits * add ref * remove unneeded include * word tweaks
1 parent f80368c commit 52ca527

File tree

5 files changed

+322
-2
lines changed

5 files changed

+322
-2
lines changed

‎snooty.toml

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,19 @@ intersphinx = [
77
"https://www.mongodb.com/docs/mongodb-shell/objects.inv"
88
]
99

10-
toc_landing_pages = ["/install", "/connect", "/instance", "/query/filter", "/query/queries",
11-
"/documents", "/schema", "/aggregation-pipeline-builder", "collections"]
10+
toc_landing_pages = [
11+
"/install",
12+
"/connect",
13+
"/connect/favorite-connections",
14+
"/connect/favorite-connections/import-export-cli/",
15+
"/instance",
16+
"/query/filter",
17+
"/query/queries",
18+
"/documents",
19+
"/schema",
20+
"/aggregation-pipeline-builder",
21+
"/collections"
22+
]
1223

1324
[constants]
1425
download-page = "`downloads page <https://www.mongodb.com/download-center/compass?tck=docs_compass>`__"

‎source/connect/favorite-connections.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,3 +60,8 @@ Considerations
6060
installed to successfully load saved connections. The Electron module
6161
`Keytar <https://github.com/atom/node-keytar>`__ uses GNOME Keyring
6262
to securely store the database credentials for your connections.
63+
64+
.. toctree::
65+
:titlesonly:
66+
67+
/connect/favorite-connections/import-export-cli

‎source/connect/favorite-connections/import-export-cli.txt

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. _compass-export-import-cli-landing:
2+
3+
===================================================
4+
Export and Import Favorite Connections with the CLI
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+
To quickly connect to a shared deployment, export and share your
16+
favorite connections. Colleagues can import your favorites, or you can
17+
use them yourself in your other workspaces.
18+
19+
.. important:: Export Contains Sensitive Information
20+
21+
By default, when you export favorite connections, database usernames
22+
and passwords are included in plaintext. To protect sensitive
23+
connection information, you may :ref:`encrypt the exported file with
24+
a passphrase <compass-export-connections-cli-encrypted>`. When you
25+
do, users must specify the matching passphrase to import the
26+
connections.
27+
28+
Tasks
29+
-----
30+
31+
To learn how to export and import favorite connections, see:
32+
33+
- :ref:`compass-export-connections-cli`
34+
35+
- :ref:`compass-import-connections-cli`
36+
37+
.. toctree::
38+
:titlesonly:
39+
40+
/connect/favorite-connections/import-export-cli/export
41+
/connect/favorite-connections/import-export-cli/import
42+

‎source/connect/favorite-connections/import-export-cli/export.txt

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
.. _compass-export-connections-cli:
2+
3+
========================================
4+
Export Favorite Connections with the CLI
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 use the |compass-short| :abbr:`CLI (Command-Line Interface)` to
16+
export favorite connections. Colleagues can import your favorites, or
17+
you can use them yourself in your other workspaces.
18+
19+
About This Task
20+
---------------
21+
22+
When you export favorite connections, |compass-short| exports the list
23+
of connections as a JSON file.
24+
25+
By default, when you export favorite connections, database usernames and
26+
passwords are included in plaintext. To protect sensitive connection
27+
information, you may encrypt the exported file with a passphrase.
28+
29+
.. _compass-export-connections-cli-encrypted:
30+
31+
Export Encrypted Favorite Connections
32+
-------------------------------------
33+
34+
This section explains to export encrypted favorite connections. When you
35+
encrypt the export file, users must specify the matching passphrase to
36+
import the connections.
37+
38+
Procedure
39+
~~~~~~~~~
40+
41+
To export encrypted favorite connections with the |compass-short|
42+
:abbr:`CLI (Command-Line Interface)`, specify:
43+
44+
- The path to the |compass| executable. The name and file path of the
45+
executable depend on your operating system.
46+
47+
- The ``--export-connections`` option set to the destination of the
48+
output file.
49+
50+
- The ``--passphrase`` option set to a passphrase used to encrypt the
51+
output file.
52+
53+
Your operation should resemble the following prototype:
54+
55+
.. code-block:: sh
56+
57+
<path-to-Compass-executable> \
58+
--export-connections=<filename> \
59+
--passphrase=<passphrase>
60+
61+
Example
62+
~~~~~~~
63+
64+
This example exports favorite |compass-short| connections to a file with
65+
the path ``/tmp/compass-connections/favorites-encrypted.json``. The exported file
66+
is encrypted with the passphrase ``abc123``.
67+
68+
Run the following command in the folder containing your MongoDB Compass
69+
executable:
70+
71+
.. code-block:: sh
72+
73+
./MongoDB\ Compass \
74+
--export-connections=/tmp/compass-connections/favorites-encrypted.json \
75+
--passphrase=abc123
76+
77+
.. note::
78+
79+
The name and file path of the executable depend on your operating
80+
system. The preceding command is for macOS.
81+
82+
You will see this output:
83+
84+
.. code-block:: sh
85+
:copyable: false
86+
87+
Exporting connections to "/tmp/compass-connections/favorites-encrypted.json" (with passphrase)
88+
89+
Results
90+
```````
91+
92+
After the export completes, the
93+
``/tmp/compass-connections/favorites-encrypted.json`` file resembles the
94+
following:
95+
96+
.. code-block:: json
97+
98+
{
99+
"type": "Compass Connections",
100+
"version": {
101+
"$numberInt": "1"
102+
},
103+
"connections": [
104+
{
105+
"id": "5a92e195-3ef5-49ae-aff6-720af362770d",
106+
"connectionOptions": {
107+
"connectionString": "mongodb+srv://[email protected]/"
108+
},
109+
"favorite": {
110+
"name": "Dochub",
111+
"color": "color7"
112+
},
113+
"lastUsed": {
114+
"$date": {
115+
"$numberLong": "1663785601002"
116+
}
117+
},
118+
"connectionSecrets": "AAGRWyDUI+Jbc9GkvSpEZeFtbvSzqtcOpA+1zLi5fma3AISOOVVBJBPqqh/a6VeNyEcf9TdX6aCqSpagXgMAOmmN0XgkJ4wxwBuSZwZH/h1dlgEFYqEG9Oh88e5z"
119+
},
120+
{
121+
"id": "655f3e6e-b13b-4813-8578-50d896bd9240",
122+
"connectionOptions": {
123+
"connectionString": "mongodb://localhost:27017/"
124+
},
125+
"favorite": {
126+
"name": "Local Host",
127+
"color": "color7"
128+
},
129+
"lastUsed": {
130+
"$date": {
131+
"$numberLong": "1663790327679"
132+
}
133+
},
134+
"connectionSecrets": "AAG63lys6oVtPmCGVs7wYkTCjFU0yXi9rYUYCKuWGNMSNBy4rAZlu06b/qDblON4OBXDJzhPNQ/WKs79veewNw=="
135+
}
136+
]
137+
}
138+
139+
Sensitive connection information is encrypted in the
140+
``connectionSecrets`` field.
141+
142+
Export Unencrypted Favorite Connections
143+
---------------------------------------
144+
145+
This section explains to export unencrypted favorite connections. If you
146+
do not encrypt the export file, database usernames and passwords are
147+
exported in plaintext. Only export unencrypted connections if no other
148+
users will have access to the exported file.
149+
150+
Procedure
151+
~~~~~~~~~
152+
153+
To export encrypted favorite connections with the |compass-short|
154+
:abbr:`CLI (Command-Line Interface)`, specify:
155+
156+
- The path to the |compass| executable. The name and file path of the
157+
executable depend on your operating system.
158+
159+
- The ``--export-connections`` option set to the destination of the
160+
output file.
161+
162+
Your operation should resemble the following prototype:
163+
164+
.. code-block:: sh
165+
166+
<path-to-Compass-executable> \
167+
--export-connections=<filename>
168+
169+
Example
170+
~~~~~~~
171+
172+
This example exports favorite |compass-short| connections to a file with
173+
the path ``/tmp/compass-connections/favorites.json``.
174+
175+
Run the following command in the folder containing your MongoDB Compass
176+
executable:
177+
178+
.. code-block:: sh
179+
180+
./MongoDB\ Compass \
181+
--export-connections=/tmp/compass-connections/favorites.json
182+
183+
.. note::
184+
185+
The name and file path of the executable depend on your operating
186+
system. The preceding command is for macOS.
187+
188+
You will see this output:
189+
190+
.. code-block:: sh
191+
:copyable: false
192+
193+
Exporting connections to "/tmp/compass-connections/favorites.json" (without passphrase)
194+
195+
Results
196+
```````
197+
198+
After the export completes, the
199+
``/tmp/compass-connections/favorites.json`` file resembles the
200+
following:
201+
202+
.. code-block:: json
203+
204+
{
205+
"type": "Compass Connections",
206+
"version": {
207+
"$numberInt": "1"
208+
},
209+
"connections": [
210+
{
211+
"id": "5a92e195-3ef5-49ae-aff6-720af362770d",
212+
"connectionOptions": {
213+
"connectionString": "<connection string>"
214+
},
215+
"favorite": {
216+
"name": "QA Cluster",
217+
"color": "color7"
218+
},
219+
"lastUsed": {
220+
"$date": {
221+
"$numberLong": "1663785601002"
222+
}
223+
}
224+
},
225+
{
226+
"id": "655f3e6e-b13b-4813-8578-50d896bd9240",
227+
"connectionOptions": {
228+
"connectionString": "mongodb://localhost:27017/"
229+
},
230+
"favorite": {
231+
"name": "Local Host",
232+
"color": "color7"
233+
},
234+
"lastUsed": {
235+
"$date": {
236+
"$numberLong": "1663790327679"
237+
}
238+
}
239+
}
240+
]
241+
}
242+
243+
Next Steps
244+
----------
245+
246+
To learn how to import exported connections, see
247+
:ref:`compass-import-connections-cli`.

‎source/connect/favorite-connections/import-export-cli/import.txt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _compass-import-connections-cli:
2+
3+
========================================
4+
Import Favorite Connections with the CLI
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+
TODO: Write

0 commit comments

Comments
 (0)