Skip to content

Commit 753f153

Browse files
jwilliams-mongojeff-allen-mongo
jwilliams-mongo
and
jeff-allen-mongo
authored
(DOCSP-9711): Connect to a MongoDB Deployment Using the VSCE (#6)
* (DOCSP-9711): initial commit - testing build * (DOCSP-9711): checkpoint * (DOCSP-9711): new checkpoint * (DOCSP-9711): first draft * (DOCSP-9711): copy review checkpoint * (DOCSP-9711): more copy review * (DOCSP-9711): another copy review fix * Updates per Max's feedback and small tweaks * copy fix Co-authored-by: jeff-allen-mongo <[email protected]>
1 parent 941fc50 commit 753f153

14 files changed

+791
-6
lines changed

‎snooty.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,6 @@ url = ":abbr:`URL (Uniform Resource Locator)`"
110110
utc = ":abbr:`UTC (Coordinated Universal Time)`"
111111
vpc = ":abbr:`VPC (Virtual Private Cloud)`"
112112
vsce = "MongoDB for VS Code"
113+
vscode = "`Microsoft Visual Studio Code <https://code.visualstudio.com/>`__"
114+
vscode-short = "Visual Studio Code"
113115
yaml = ":abbr:`YAML (Yet Another Markup Language)`"

‎source/connect.txt

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,162 @@ Connect to Your MongoDB Deployment
1313
:class: singlecol
1414

1515
.. include:: /includes/fact-vsce-preview.rst
16+
17+
This page outlines how to use |vcse| to connect to a
18+
MongoDB host. You can connect to a standalone, replica set,
19+
or sharded cluster host.
20+
21+
.. admonition:: MongoDB Atlas
22+
:class: note
23+
24+
If you need to create a MongoDB host, consider using
25+
`MongoDB Atlas <https://www.mongodb.com/cloud/atlas?tck=docs_vsce>`__.
26+
Atlas is a cloud-hosted database-as-a-service which requires no
27+
installation, offers a free tier to get started, and provides a
28+
copyable URI to easily connect |vsce| to your deployment.
29+
30+
If you need to install |vsce|, see :ref:`vsce-install` for instructions.
31+
32+
Considerations
33+
--------------
34+
35+
- When connecting |vsce| to a replica set, use either the
36+
replica set :guilabel:`SRV record` or :guilabel:`Replica Set Name`
37+
when filling in your connection information. It is not recommended to
38+
connect directly to an individual replica set member.
39+
40+
- If the member to which you are connected switches from a
41+
:manual:`primary </core/replica-set-primary/>` member to a
42+
:manual:`secondary </core/replica-set-secondary/>` or vice versa as
43+
the result of an election, |vsce| may either forcibly close
44+
the connection or display stale data.
45+
46+
- You can't connect |vsce| directly to an :atlas:`analytics node
47+
<faq/#what-are-analytics-nodes>`.
48+
49+
- |vsce| appends the ``appName`` connection string option with a value
50+
of ``mongodb-vscode <version>`` for all deployment connections.
51+
52+
.. - If you are using Kerberos as your authentication mechanism, do not
53+
.. specify the :guilabel:`Password` in the connection form.
54+
55+
.. _vsce-connect-task:
56+
57+
Create a Connection to a Deployment
58+
-----------------------------------
59+
60+
|vsce| provides two methods to create a connection to a deployment. You
61+
can:
62+
63+
- Provide a deployment connection string, or
64+
- Fill in a deployment information in specific fields.
65+
66+
Providing a connection string is faster and easier than filling in a
67+
deployment's details. Use this option if |service| hosts your
68+
deployment or if you have a connection string for a deployment
69+
available.
70+
71+
Define how your connection is saved with the
72+
:guilabel:`Default Connection Saving Location`
73+
:ref:`setting <vsce-settings>`:
74+
75+
.. list-table::
76+
:header-rows: 1
77+
:widths: 20 40
78+
79+
* - Setting
80+
- Description
81+
82+
* - ``Global``
83+
- Save your connection globally in VS Code, so it can be accessed
84+
from any workspace.
85+
86+
* - ``Workspace``
87+
- Save your connection in your workspace. You cannot
88+
access the connection from a different workspace.
89+
90+
* - ``Session``
91+
- Save the connection for only this VS Code session. The connection
92+
is lost when you close VS Code.
93+
94+
.. tabs::
95+
96+
.. tab:: Paste Connection String
97+
:tabid: paste-connection-string
98+
99+
When you provide a connection string, |vsce| supports
100+
most :manual:`Connection String Options
101+
</reference/connection-string/#connection-string-options>`
102+
supported by MongoDB.
103+
104+
.. include:: /includes/steps/starting-vsce-paste-string.rst
105+
106+
.. tab:: Fill in Individual Fields
107+
:tabid: individual-fields
108+
109+
.. include:: /includes/steps/starting-vsce-individual-fields.rst
110+
111+
.. _vsce-activate-connection:
112+
113+
Activate a Connection
114+
---------------------
115+
116+
You can connect |vsce| to only one deployment at a time. To change the
117+
active connection to a different deployment, or to connect to a
118+
deployment from which you were disconnected:
119+
120+
.. include:: /includes/steps/activate-connection.rst
121+
122+
.. _vsce-disconnect-task:
123+
124+
Disconnect from a Deployment
125+
----------------------------
126+
127+
|vsce| provides two methods to disconnect from a deployment. You can:
128+
129+
- Disconnect with the Command Palette, or
130+
- Disconnect from the :guilabel:`MongoDB` view in the
131+
:guilabel:`Activity Bar`.
132+
133+
.. tabs::
134+
135+
.. tab:: Disconnect with the Command Palette
136+
:tabid: command-palette
137+
138+
.. include:: /includes/steps/disconnect-command-palette.rst
139+
140+
.. tab:: Disconnect from the MongoDB View
141+
:tabid: mdb-view
142+
143+
.. include:: /includes/steps/disconnect-mongodb-view.rst
144+
145+
Disconnecting from a MongoDB instance closes the |vsce| connection to
146+
the active instance. You must :ref:`reconnect <vsce-connect-task>` to
147+
interact with data in your deployment again.
148+
149+
Remove a Connection
150+
-------------------
151+
152+
|vsce| provides two methods to remove a connection to a deployment from
153+
|vscode-short|. You can:
154+
155+
- Remove a connection with the Command Palette, or
156+
- Remove a connection from the :guilabel:`MongoDB` view in the
157+
:guilabel:`Activity Bar`.
158+
159+
.. important::
160+
161+
Removing a connection from |vscode-short| removes it both from the
162+
current workspace and from |vscode-short| globally.
163+
164+
.. tabs::
165+
166+
.. tab:: Remove Connection with the Command Palette
167+
:tabid: command-palette
168+
169+
.. include:: /includes/steps/remove-connection-command-palette.rst
170+
171+
.. tab:: Remove Connection from the MongoDB View
172+
:tabid: mdb-view
173+
174+
.. include:: /includes/steps/remove-connection-mdb-view.rst

‎source/includes/admonitions/tip-mongodb-command-palette.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. tip::
2+
3+
Enter ``mongodb`` in the Command Palette to display all of the
4+
|vsce| commands you can use.

‎source/includes/list-tables/command-palette-options.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:widths: 33 33 34
4+
5+
* - Operating System
6+
- Method
7+
- Actions
8+
9+
* - Any
10+
- |vscode-short| Menu
11+
- :guilabel:`View` > :guilabel:`Command Palette`
12+
13+
* - MacOS
14+
- Keyboard Shortcut
15+
- Press ``Command`` + ``Shift`` + ``P``
16+
17+
* - Windows and Linux
18+
- Keyboard Shortcut
19+
- Press ``Control`` + ``Shift`` + ``P``

‎source/includes/steps-activate-connection.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
ref: nav-to-mdb-view
3+
source:
4+
file: steps-open-mongodb-view.yaml
5+
ref: open-mongodb-view
6+
---
7+
title: "Right-click the connection you want to activate, then click :guilabel:`Connect`."
8+
level: 4
9+
ref: activate-connection
10+
...

‎source/includes/steps-disconnect-command-palette.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
source:
3+
file: steps-source-command-palette.yaml
4+
ref: vsce-command-palette
5+
ref: vsce-connect-command-palette
6+
---
7+
title: Disconnect.
8+
level: 4
9+
ref: vsce-disconnect
10+
content: |
11+
12+
#. From the Command Palette, select
13+
:guilabel:`MongoDB: Disconnect`.
14+
15+
.. include:: /includes/admonitions/tip-mongodb-command-palette.rst
16+
17+
#. Press **Enter**.
18+
19+
...

‎source/includes/steps-disconnect-mongodb-view.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
source:
3+
file: steps-open-mongodb-view.yaml
4+
ref: open-mongodb-view
5+
ref: disconnect-open-mongodb-view
6+
---
7+
title: "Right-click the deployment from which you want to disconnect, then click :guilabel:`Disconnect`."
8+
level: 4
9+
ref: vsce-disconnect
10+
11+
...

‎source/includes/steps-open-mongodb-view.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "In |vscode-short|, click the :guilabel:`MongoDB` view in the :guilabel:`Activity Bar`."
3+
level: 4
4+
ref: open-mongodb-view
5+
...

‎source/includes/steps-remove-connection-command-palette.yaml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
source:
3+
file: steps-source-command-palette.yaml
4+
ref: vsce-command-palette
5+
ref: vsce-remove-command-palette
6+
---
7+
title: "From the Command Palette, select
8+
:guilabel:`MongoDB: Remove Connection...`."
9+
level: 4
10+
ref: vsce-remove-remove
11+
content: |
12+
13+
.. include:: /includes/admonitions/tip-mongodb-command-palette.rst
14+
15+
If you have more than one connection, select the connection you want
16+
to remove from the Command Palette.
17+
---
18+
title: "Click :guilabel:`Yes` to remove the connection."
19+
ref: confirm-connection-remove
20+
level: 4
21+
...

‎source/includes/steps-remove-connection-mdb-view.yaml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
source:
3+
file: steps-open-mongodb-view.yaml
4+
ref: open-mongodb-view
5+
ref: disconnect-open-mongodb-view
6+
---
7+
title: "Right-click the connection you want to remove, then click :guilabel:`Remove Connection`."
8+
level: 4
9+
ref: remove-connection-mdb-view
10+
---
11+
title: "Click :guilabel:`Yes` to remove the connection."
12+
level: 4
13+
ref: remove-connection-confirm
14+
...

‎source/includes/steps-source-command-palette.yaml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "In |vscode-short|, open the Command Palette."
3+
level: 4
4+
ref: vsce-command-palette
5+
content: |
6+
7+
.. include:: /includes/list-tables/command-palette-options.rst
8+
---
9+
title: "From the Command Palette, choose where you want to save the
10+
connection."
11+
level: 4
12+
ref: vsce-connect-save
13+
content: |
14+
15+
.. list-table::
16+
:header-rows: 1
17+
:widths: 50 50
18+
:stub-columns: 1
19+
20+
* - Option
21+
- Description
22+
23+
* - Save the connection on this workspace
24+
- The connection is available only when you open the workspace in
25+
which you created the connection in |vscode-short|.
26+
27+
* - Save the connection globally on vscode
28+
- The connection is available whenever you open |vscode-short|.
29+
30+
* - Don't save this connection
31+
- The connection is available until you close |vscode-short|.
32+
33+
.. admonition:: Required Access
34+
:class: important
35+
36+
Once you are connected to your MongoDB deployment, you may
37+
require specific :manual:`user roles <reference/built-in-roles/>`
38+
to access various |vsce| features.
39+
40+
...

0 commit comments

Comments
 (0)