Skip to content

Commit 39f53fd

Browse files
nickldprustagir
nickldp
and
rustagir
authored
Docsp 30505 quick start pages (#13)
Co-authored-by: Rea Rustagi <[email protected]>
1 parent a32f4c0 commit 39f53fd

File tree

13 files changed

+374
-3
lines changed

13 files changed

+374
-3
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,6 @@ driver-short = "Rust driver"
1919
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.)
22+
min-rust-version = "1.57" # always set this to the minimum supported Rust version
2223
api = "https://docs.rs/mongodb/{+version+}/mongodb"
2324
stable-api = "Stable API"

‎source/code-snippets/quick-start/connect-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, Client, Collection };
2+
use bson:: Document;
3+
4+
#[tokio::main]
5+
async fn main() -> mongodb::error::Result<()> {
6+
// Replace the placeholder with your Atlas connection string
7+
let uri = "<connection string>";
8+
9+
// Create a new client and connect to the server
10+
let client = Client::with_uri_str(uri).await?;
11+
12+
// Get a handle on the "movies" collection in the "sample_mflix" database
13+
let my_coll: Collection<Document> = client.database("sample_mflix").collection("movies");
14+
15+
// Find the movie "The Perils of Pauline" in the "movies" collection
16+
let my_movie = my_coll.find_one(doc! { "title": "The Perils of Pauline" }, None).await?;
17+
18+
// Print the document that contains the movie found
19+
println!("{}", serde_json::to_string_pretty(&my_movie).unwrap());
20+
Ok(())
21+
}

‎source/code-snippets/quick-start/connect-sync.rs

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
use mongodb::{ bson::doc, sync::{Client} };
2+
use bson:: Document;
3+
4+
fn main() -> mongodb::error::Result<()> {
5+
// Replace the placeholder with your Atlas connection string
6+
let uri = "<connection string>";
7+
8+
// Create a new client and connect to the server
9+
let client = Client::with_uri_str(uri);
10+
11+
// Get a handle on the "movies" collection in the "sample_mflix" database
12+
let database = client?.database("sample_mflix");
13+
let my_coll = database.collection::<Document>("movies");
14+
15+
// Find the movie "The Perils of Pauline" in the "movies" collection
16+
let my_movie = my_coll.find_one(doc! { "title": "The Perils of Pauline" }, None)?;
17+
18+
// Print the document that contains the movie found
19+
println!("{}", serde_json::to_string_pretty(&my_movie).unwrap());
20+
Ok(())
21+
}
22+
23+

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,8 @@ connection code samples.
133133
<atlas-serverless-drivers>` to identify the minimum driver version
134134
you need.
135135

136+
.. _rust-other-ways-to-connect:
137+
136138
--------------------------------
137139
Other Ways to Connect to MongoDB
138140
--------------------------------

‎source/includes/figures/atlas_connection_select_cluster.png

34.6 KB
Loading

‎source/includes/quick-start/troubleshoot.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. note::
2+
3+
If you run into issues on this step, ask for help in the
4+
:community-forum:`MongoDB Community Forums <tag/rust/>`
5+
or submit feedback using the :guilabel:`Share Feedback`
6+
tab on the right or bottom right side of this page.

‎source/index.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@
66
:titlesonly:
77
:maxdepth: 1
88

9+
/quick-start
910
/fundamentals
1011
API Documentation <{+api+}/>
1112
/issues-and-help
1213
/compatibility
1314
View the Source <https://github.com/mongodb/mongo-rust-driver>
1415

1516
..
16-
/quick-start
1717
/quick-reference
1818
/whats-new
1919
/usage-examples
@@ -31,8 +31,8 @@ runnable project by following the Quick Start guide.
3131
Quick Start
3232
-----------
3333

34-
.. Learn how to establish a connection to MongoDB Atlas and begin
35-
.. working with data in the :ref:`rust-quickstart` section.
34+
Learn how to establish a connection to MongoDB Atlas and begin
35+
working with data in the :ref:`rust-quickstart` section.
3636

3737
Quick Reference
3838
---------------

‎source/quick-start.txt

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
.. _rust-quickstart:
2+
3+
===========
4+
Quick Start
5+
===========
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
This guide shows you how to create an application that uses the
17+
{+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. If
18+
you prefer to connect to MongoDB using a different driver or programming
19+
language, see our :driver:`list of official drivers <>`.
20+
21+
The {+driver-short+} is a library of functions that you can use to connect
22+
to and communicate with MongoDB.
23+
24+
MongoDB Atlas is a fully managed cloud database service that hosts your
25+
MongoDB deployments. You can create your own free (no credit card
26+
required) MongoDB Atlas deployment by following the steps in this guide.
27+
28+
Follow the steps in this guide to connect a sample Rust application to
29+
a MongoDB Atlas deployment.
30+
31+
.. button:: Next: Download and Install
32+
:uri: /quick-start/download-and-install/
33+
34+
.. toctree::
35+
36+
/quick-start/download-and-install/
37+
/quick-start/create-a-deployment/
38+
/quick-start/create-a-connection-string/
39+
/quick-start/connect-to-mongodb/
40+
/quick-start/next-steps/

‎source/quick-start/connect-to-mongodb.txt

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
.. _rust-quick-start-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. procedure::
8+
:style: connected
9+
10+
.. step:: Create your Rust Application
11+
12+
Open the file called ``main.rs`` in your
13+
``rust_quickstart/src`` project directory. In this file, you can
14+
begin writing your application.
15+
16+
Copy and paste the following code into the ``main.rs`` file:
17+
18+
.. tabs::
19+
20+
.. tab:: Asynchronous API
21+
:tabid: asynchronous-api
22+
23+
.. literalinclude:: /code-snippets/quick-start/connect-async.rs
24+
:language: rust
25+
26+
.. tab:: Synchronous API
27+
:tabid: synchronous-api
28+
29+
.. literalinclude:: /code-snippets/quick-start/connect-sync.rs
30+
:language: rust
31+
32+
.. step:: Assign the Connection String
33+
34+
Replace the ``<connection string>`` placeholder with the
35+
connection string that you copied from the :ref:`rust-quick-start-connection-string`
36+
step of this guide.
37+
38+
.. step:: Run your Rust Application
39+
40+
In your shell, run the following command to compile and run this application:
41+
42+
.. code-block:: none
43+
44+
cargo run
45+
46+
You should see the details of the retrieved movie document in the
47+
command line output:
48+
49+
.. code-block:: none
50+
51+
{
52+
"_id": { ... },
53+
"plot": "Young Pauline is left a lot of money when her wealthy ...";
54+
"genres": [
55+
"Action"
56+
],
57+
"runtime": 199,
58+
"cast": [
59+
"Pearl White",
60+
"Crane Wilbur",
61+
"Paul Panzer",
62+
"Edward Josè"
63+
],
64+
...
65+
}
66+
67+
If you encounter an error or see no output, check whether you specified the
68+
proper connection string in the ``main.rs`` file, and that you loaded the
69+
sample data.
70+
71+
After you complete these steps, you should have a working application that
72+
uses the driver to connect to your MongoDB deployment, runs a query on
73+
the sample data, and prints out the result.
74+
75+
.. include:: /includes/quick-start/troubleshoot.rst
76+
77+
.. button:: Next Steps
78+
:uri: /quick-start/next-steps/

‎source/quick-start/create-a-connection-string.txt

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. _rust-quick-start-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
To connect to an instance or deployment not hosted on Atlas, see
17+
:ref:`Other Ways to Connect to MongoDB <rust-other-ways-to-connect>`.
18+
19+
.. procedure::
20+
:style: connected
21+
22+
.. step:: Find your MongoDB Atlas Connection String
23+
24+
To retrieve your connection string for the deployment that
25+
you created in the :ref:`previous step <rust-quick-start-create-deployment>`,
26+
log into your Atlas account and navigate to the
27+
:guilabel:`Database` section and click the :guilabel:`Connect` button
28+
for your new deployment.
29+
30+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
31+
:alt: The connect button in the clusters section of the Atlas UI
32+
33+
Proceed to the :guilabel:`Connect your application` section and select
34+
"Rust" from the :guilabel:`Driver` selection menu and the version
35+
that best matches the version you installed from the :guilabel:`Version`
36+
selection menu.
37+
38+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
39+
40+
Deselect the :guilabel:`Include full driver code example` to view
41+
the connection string.
42+
43+
.. step:: Copy your Connection String
44+
45+
Click the button on the right of the connection string to copy it to
46+
your clipboard as shown in the following screenshot:
47+
48+
.. TODO add image when bug is resolved https://jira.mongodb.org/browse/AG-925
49+
50+
.. step:: Update the Placeholders
51+
52+
Paste this connection string into a a file in your preferred text editor
53+
and replace the ``<username>`` and ``<password>`` placeholders with
54+
your database user's username and password.
55+
56+
Save this file to a safe location for use in the next step.
57+
58+
After completing these steps, you should have a connection string that
59+
contains your database username and password.
60+
61+
.. include:: /includes/quick-start/troubleshoot.rst
62+
63+
.. button:: Next: Connect to MongoDB
64+
:uri: /quick-start/connect-to-mongodb/

0 commit comments

Comments
 (0)