Skip to content

Commit 430d149

Browse files
rustagirrustagir
authored
DOCSP-30523: connection guide (#8)
1 parent e20d84f commit 430d149

File tree

10 files changed

+294
-11
lines changed

10 files changed

+294
-11
lines changed

‎snooty.toml

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

99
toc_landing_pages = [
10-
"/fundamentals/connection",
10+
"/fundamentals/connections",
1111
"/fundamentals/crud"
1212
]
1313

@@ -20,4 +20,4 @@ server = "MongoDB Server"
2020
docs-branch = "master" # always set this to the docs branch (i.e. master, v2.6, v2.5, etc.)
2121
version = "2.6.0" # always set this to the driver version (i.e. 2.6.0, 2.5.0, etc.)
2222
api = "https://docs.rs/mongodb/{+version+}/mongodb"
23-
stable-api = "Stable API"
23+
stable-api = "Stable API"

‎source/compatibility.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,5 @@ Language Compatibility
2727

2828
.. include:: /includes/language-compatibility-table-rust.rst
2929

30-
For more information on how to read the compatibility tables, see our guide on
30+
For more information on how to read the compatibility tables, see the guide on
3131
:ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.

‎source/fundamentals/connections.txt

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@ Connections
66

77
.. toctree::
88

9+
/fundamentals/connections/connection-guide
10+
911
..
10-
/fundamentals/connection/connection-guide
11-
/fundamentals/connection/connection-options
12-
/fundamentals/connection/network-compression
13-
/fundamentals/connection/tls
12+
/fundamentals/connections/connection-options
13+
/fundamentals/connections/network-compression
14+
/fundamentals/connections/tls
1415
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
1516

1617
.. contents:: On this page
@@ -25,7 +26,8 @@ Overview
2526
Learn how to configure your application's connection to a MongoDB
2627
deployment using the {+driver-short+} in the following sections:
2728

28-
.. - :ref:`Connect to MongoDB <rust-connect-to-mongodb>`
29+
- :ref:`Connection Guide <rust-connect-to-mongodb>`
30+
2931
.. - :ref:`Connection Options <rust-connection-options>`
3032
.. - :ref:`Enable Network Compression <rust-network-compression>`
3133
.. - :ref:`Enable TLS on a Connection <rust-connect-tls>`

‎source/fundamentals/connections/connection-guide.txt

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
.. _rust-connect-to-mongodb:
2+
3+
================
4+
Connection Guide
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
This guide shows you how to connect to a MongoDB instance or replica set
14+
deployment using the {+driver-short+}.
15+
16+
.. _rust-connection-uri:
17+
18+
--------------
19+
Connection URI
20+
--------------
21+
22+
A **connection URI**, also known as a connection string, tells the
23+
driver how to connect to MongoDB and how to behave while connected.
24+
25+
Parts of a Connection URI
26+
~~~~~~~~~~~~~~~~~~~~~~~~~
27+
28+
The following example explains each part of a sample connection URI:
29+
30+
.. figure:: /includes/figures/connection_uri_parts.png
31+
:alt: Parts of a connection URI
32+
33+
In this example, we use ``mongodb`` for the protocol, which specifies the
34+
:manual:`Standard Connection String Format
35+
</reference/connection-string/#std-label-connections-standard-connection-string-format>`.
36+
You can also use the :manual:`DNS Seed List Connection Format
37+
</reference/connection-string/#dns-seed-list-connection-format>` if you
38+
want more flexibility in your deployment and the ability to change the
39+
servers in rotation without reconfiguring clients.
40+
41+
If you are using password-based authentication, the part of the
42+
connection string after the protocol contains your username and
43+
password. Replace the placeholder for ``user`` with your username and
44+
``pass`` with your password. If you are using an authentication
45+
mechanism that does not require a username and password, omit
46+
this part of the connection URI.
47+
48+
The part of the connection string after the credentials specifies the
49+
hostname or IP address and port of your MongoDB instance. In the
50+
preceding example, we use ``sample.host`` as the hostname and ``27017``
51+
as the port. Replace these values to point to your MongoDB instance.
52+
53+
The last part of the connection string specifies connection and authentication
54+
options. In the example, we set two connection options:
55+
``maxPoolSize=20`` and ``w=majority``.
56+
57+
.. TODO To learn more about connection
58+
.. options, see the :ref:`rust-connection-options` reference.
59+
60+
MongoDB Client
61+
~~~~~~~~~~~~~~
62+
63+
To connect to MongoDB, you need to create a ``Client`` instance. A
64+
client manages your connections and runs database commands.
65+
66+
.. tip:: Reuse Your Client
67+
68+
We recommend that you reuse your client across sessions and operations.
69+
You can use the same ``Client`` instance to perform multiple tasks, instead of
70+
creating a new one each time. The ``Client`` type is safe for
71+
concurrent use by multiple threads or async tasks.
72+
73+
.. TODO To learn more about how connection pools work in the driver, see
74+
.. the :ref:`FAQ page <rust-faq-connection-pool>`.
75+
76+
You can create a client that uses your connection string and other
77+
client options by passing a ``ClientOptions`` object to the ``with_options()``
78+
method.
79+
80+
To specify your connection URI, pass it to the ``parse()``
81+
method of ``ClientOptions``. To set any other
82+
options, set the relevant field of the ``ClientOptions`` struct.
83+
84+
.. TODO To learn more about connection options, see the
85+
.. :ref:`Connection Options <rust-connection-options>` reference.
86+
87+
To learn more about creating a client, see the API documentation for `Client
88+
<{+api+}/struct.Client.html>`__ and `with_options() <{+api+}/struct.Client.html#method.with_options>`__.
89+
90+
You can set the {+stable-api+} version as an option to avoid
91+
breaking changes when you upgrade to a new server version.
92+
93+
.. TODO To learn more about the {+stable-api+} feature, see the
94+
.. :ref:`{+stable-api+} page <rust-stable-api>`.
95+
96+
.. _rust-atlas-connection-example:
97+
98+
Connection Example
99+
~~~~~~~~~~~~~~~~~~
100+
101+
The following code shows how you can create a client that uses an Atlas
102+
connection string and the {+stable-api+} version, connect to MongoDB, and
103+
verify that the connection is successful. Select from the
104+
:guilabel:`Sync` or :guilabel:`Async` tabs below for corresponding
105+
connection code samples.
106+
107+
.. TODO To learn more about asynchronous and synchronous runtimes, see the
108+
.. :ref:`Runtimes <TODO link>` guide.
109+
110+
.. tabs::
111+
112+
.. tab:: Async
113+
:tabid: rust-async
114+
115+
.. literalinclude:: /includes/fundamentals/code-snippets/connection-async.rs
116+
:language: rust
117+
118+
.. tab:: Sync
119+
:tabid: rust-sync
120+
121+
.. literalinclude:: /includes/fundamentals/code-snippets/connection-sync.rs
122+
:language: rust
123+
124+
.. .. tip::
125+
..
126+
.. TODO Follow the :ref:`Quick Start guide <rust-connect-to-your-cluster>`
127+
.. to retrieve your Atlas connection string.
128+
129+
.. note::
130+
131+
To learn about connecting to Atlas Serverless, see the
132+
:ref:`Serverless Instance Limitations page
133+
<atlas-serverless-drivers>` to identify the minimum driver version
134+
you need.
135+
136+
--------------------------------
137+
Other Ways to Connect to MongoDB
138+
--------------------------------
139+
140+
If you need to connect to a single MongoDB server instance or replica set
141+
that is not hosted on Atlas, see the following sections to find out how to
142+
connect.
143+
144+
Connect to a MongoDB Server on Your Local Machine
145+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146+
147+
.. include:: /includes/localhost-connection.rst
148+
149+
Connect to a Replica Set
150+
~~~~~~~~~~~~~~~~~~~~~~~~
151+
152+
A MongoDB replica set deployment is a group of connected instances, or nodes,
153+
where the nodes store the same set of data. This configuration of instances
154+
provides data redundancy and high data availability.
155+
156+
To connect to a replica set deployment, specify the hostname and port numbers
157+
of each instance, separated by commas, and the replica set name as the value
158+
of the ``replicaSet`` parameter in the connection string.
159+
160+
In the following example, the hostnames are ``host1``, ``host2``, and
161+
``host3``, and the port numbers are all ``27017``. The replica set name
162+
is ``myRS``. The following code shows the connection URI for the replica
163+
set with these specifications:
164+
165+
.. code-block:: none
166+
167+
mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS
168+
169+
When connecting to a replica set, the driver takes the following actions by default:
170+
171+
- Discovers all replica set members when given the address of any one member.
172+
- Dispatches operations to the appropriate member, such as instructions
173+
to write against the **primary** node. To learn more about the replica
174+
set primary, see :manual:`Replica Set Primary </core/replica-set-primary/>` in the Server manual.
175+
176+
.. tip::
177+
178+
You only need to specify one host to connect to a replica set.
179+
However, to ensure connectivity when the specified host
180+
is unavailable, you should provide the full list of hosts.
181+
182+
Direct Connection
183+
`````````````````
184+
185+
To force operations on the host designated in the connection URI,
186+
specify the ``directConnection`` option. Direct connections display the
187+
following behavior:
188+
189+
- They don't support SRV strings.
190+
- They fail on writes when the specified host is not the primary.
191+
- They require you to :manual:`specify a secondary read preference
192+
</core/read-preference/#mongodb-readmode-secondary>` when the
193+
specified host isn't the primary member. To learn more about these
194+
replica set members, see :manual:`Replica Set Secondary Members
195+
</core/replica-set-secondary/>` in the Server manual.

‎source/includes/figures/connection_uri_parts.png

5.92 KB
Loading

‎source/includes/fundamentals/code-snippets/connection-async.rs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, Client };
2+
3+
#[tokio::main]
4+
async fn main() -> mongodb::error::Result<()> {
5+
// Replace the placeholder with your Atlas connection string
6+
let uri = "<connection string>";
7+
let mut client_options = ClientOptions::parse(uri).await?;
8+
9+
// Set the server_api field of the client_options object to Stable API version 1
10+
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
11+
client_options.server_api = Some(server_api);
12+
13+
// Create a new client and connect to the server
14+
let client = Client::with_options(client_options)?;
15+
16+
// Send a ping to confirm a successful connection
17+
client.database("admin").run_command(doc! { "ping": 1 }, None).await?;
18+
println!("Pinged your deployment. You successfully connected to MongoDB!");
19+
20+
Ok(())
21+
}

‎source/includes/fundamentals/code-snippets/connection-sync.rs

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, sync::Client };
2+
3+
fn main() -> mongodb::error::Result<()> {
4+
// Replace the placeholder with your Atlas connection string
5+
let uri = "<connection string>";
6+
let mut client_options = ClientOptions::parse(uri)?;
7+
8+
// Set the server_api field of the client_options object to Stable API version 1
9+
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
10+
client_options.server_api = Some(server_api);
11+
12+
// Create a new client and connect to the server
13+
let client = Client::with_options(client_options)?;
14+
15+
// Send a ping to confirm a successful connection
16+
client.database("admin").run_command(doc! { "ping": 1 }, None)?;
17+
println!("Pinged your deployment. You successfully connected to MongoDB!");
18+
19+
Ok(())
20+
}

‎source/includes/localhost-connection.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
If you need to run the {+server+} on your local machine for development
2+
purposes, you must complete the following:
3+
4+
1. Follow the :manual:`Install MongoDB </installation/>` tutorial to
5+
install the {+server+} on your machine. Select the appropriate
6+
installation tutorial for your machine and operating system.
7+
8+
#. After you complete the installation, start the server.
9+
10+
.. important::
11+
12+
Always secure your server from malicious attacks. See the
13+
:manual:`Security Checklist </administration/security-checklist/>` for a
14+
list of security recommendations.
15+
16+
After you successfully start the {+server+}, connect to your local
17+
instance by performing the following steps:
18+
19+
1. Replace the connection string stored in the ``uri`` variable in the
20+
:ref:`preceding example <rust-atlas-connection-example>` with the
21+
connection string for your local MongoDB instance.
22+
23+
If your {+server+} is running locally, you can use the following
24+
connection string to connect to MongoDB:
25+
26+
.. code-block:: none
27+
28+
mongodb://localhost:<port>
29+
30+
In this connection string, ``<port>`` is the port number you
31+
configured your server to listen for incoming connections.
32+
33+
#. Run the connection code. If the code executes successfully, you should see
34+
the following output in your console:
35+
36+
.. code-block:: none
37+
:copyable: false
38+
39+
Pinged your deployment. You successfully connected to MongoDB!
40+
41+
.. seealso::
42+
43+
To learn more about connection strings and custom formats, see
44+
:manual:`Connection Strings </reference/connection-string/>` in the
45+
Server manual.

‎source/index.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Introduction
2626
Welcome to the documentation site for the official {+driver-long+}.
2727
You can add the driver to your application to work with MongoDB in Rust.
2828
Import it by adding it to your project's ``Cargo.toml`` file or set up a
29-
runnable project by following our Quick Start guide.
29+
runnable project by following the Quick Start guide.
3030

3131
Quick Start
3232
-----------

‎source/issues-and-help.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@ with varying levels of experience using the {+driver-short+}. The
99
quickest way to get support for general questions is through the
1010
`MongoDB Community Forums <https://www.mongodb.com/community/forums/>`_.
1111

12-
To learn more, refer to our `support channels
12+
To learn more, refer to the `support channels
1313
<http://www.mongodb.org/about/support>`_.
1414

1515
Bugs / Feature Requests
1616
-----------------------
1717

1818
If you think you've found a bug or want to request a new feature in the
19-
{+driver-short+}, please open a case in our issue management tool,
19+
{+driver-short+}, please open a case in MongoDB's issue management tool,
2020
JIRA, by performing the following steps:
2121

2222
1. Visit the `MongoDB JIRA issue tracker <https://jira.mongodb.org/>`__ and click the

0 commit comments

Comments
 (0)