|
4 | 4 | Quick Start |
5 | 5 | =========== |
6 | 6 |
|
7 | | -.. default-domain:: mongodb |
8 | | - |
9 | 7 | .. contents:: On this page |
10 | 8 | :local: |
11 | 9 | :backlinks: none |
12 | | - :depth: 2 |
| 10 | + :depth: 1 |
13 | 11 | :class: singlecol |
14 | 12 |
|
| 13 | +Overview |
| 14 | +-------- |
| 15 | + |
15 | 16 | This guide shows you how to create an application that uses the |
16 | 17 | {+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. If |
17 | 18 | you prefer to connect to MongoDB using a different driver or programming |
18 | 19 | language, see our :driver:`list of official drivers <>`. |
19 | 20 |
|
20 | | -The {+driver-short+} is a library you can use to connect to and communicate |
21 | | -with MongoDB. |
| 21 | +The {+driver-short+} is a library of functions that you can use to connect |
| 22 | +to and communicate with MongoDB. |
22 | 23 |
|
23 | 24 | MongoDB Atlas is a fully managed cloud database service that hosts your |
24 | | -MongoDB servers. You can get started with your own free (no credit card |
25 | | -required) MongoDB instance with this guide. |
26 | | - |
27 | | -Follow the steps below to connect a sample Node.js application to a MongoDB |
28 | | -instance on MongoDB Atlas. |
29 | | - |
30 | | -Set up Your Project |
31 | | -------------------- |
32 | | - |
33 | | -Install Node and npm |
34 | | -~~~~~~~~~~~~~~~~~~~~ |
35 | | - |
36 | | -Ensure you have Node.js v12 or later and npm (Node Package Manager) installed |
37 | | -in your development environment. |
38 | | - |
39 | | -For information on how to install Node.js and npm, see |
40 | | -`downloading and installing Node.js and npm <https://docs.npmjs.com/downloading-and-installing-node-js-and-npm>`__. |
41 | | - |
42 | | - |
43 | | -Create the Project |
44 | | -~~~~~~~~~~~~~~~~~~ |
45 | | - |
46 | | -First, in your shell, create a directory for your project: |
47 | | - |
48 | | -.. code-block:: bash |
49 | | - |
50 | | - mkdir node_quickstart |
51 | | - |
52 | | -Then, navigate into that directory: |
53 | | - |
54 | | -.. code-block:: bash |
55 | | - |
56 | | - cd node_quickstart |
57 | | - |
58 | | -Next, initialize your project: |
59 | | - |
60 | | -.. code-block:: bash |
61 | | - |
62 | | - npm init -y |
63 | | - |
64 | | -Add MongoDB as a Dependency |
65 | | -~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
66 | | - |
67 | | -Install the {+driver-short+}: |
68 | | - |
69 | | -.. code-block:: bash |
70 | | - |
71 | | - npm install mongodb@{+version+} |
72 | | - |
73 | | -This command performs the following actions: |
74 | | - |
75 | | -- Downloads the ``mongodb`` package and the dependencies it requires |
76 | | -- Saves the package in the ``node_modules`` directory |
77 | | -- Records the dependency information in the ``package.json`` file |
78 | | - |
79 | | -At this point, you are ready to use the {+driver-short+} with your |
80 | | -application. |
81 | | - |
82 | | -.. _node-quickstart-connect-cluster: |
83 | | - |
84 | | -Create a MongoDB Cluster |
85 | | -~~~~~~~~~~~~~~~~~~~~~~~~ |
86 | | - |
87 | | -.. procedure:: |
88 | | - :style: connected |
89 | | - |
90 | | - .. step:: Create a Free Tier Cluster in Atlas |
91 | | - |
92 | | - Create a free tier MongoDB cluster on MongoDB Atlas to store and manage |
93 | | - your data. MongoDB Atlas hosts and manages your MongoDB database in the |
94 | | - cloud. Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_nodejs>` |
95 | | - guide to set up a new Atlas account, a free tier cluster (a shared |
96 | | - MongoDB instance) and load sample data into your cluster. |
97 | | - |
98 | | - .. step:: Connect to your Cluster |
99 | | - |
100 | | - You can connect to your MongoDB cluster by providing a |
101 | | - **connection string** which instructs the driver on where and how to |
102 | | - connect. The connection string includes information on the hostname |
103 | | - or IP address and port of your cluster, the authentication mechanism, |
104 | | - user credentials when applicable, and other connection options. |
105 | | - |
106 | | - To connect to an instance or cluster not hosted on Atlas, see |
107 | | - :ref:`Other Ways to Connect to MongoDB <node-other-ways-to-connect>`. |
108 | | - |
109 | | - To retrieve your connection string for the cluster you created in |
110 | | - the previous step, log into your Atlas account and navigate to the |
111 | | - :guilabel:`Database` section and click the :guilabel:`Connect` button |
112 | | - for the cluster that you want to connect to as shown below. |
113 | | - |
114 | | - .. figure:: /includes/figures/atlas_connection_select_cluster.png |
115 | | - :alt: The connect button in the clusters section of the Atlas UI |
116 | | - |
117 | | - Proceed to the :guilabel:`Connect Your Application` section and select |
118 | | - the {+driver-short+}. Select the :guilabel:`Connection String Only` tab |
119 | | - and click the :guilabel:`Copy` button to copy the connection string to |
120 | | - your clipboard as shown below. |
121 | | - |
122 | | - .. figure:: /includes/figures/atlas_connection_copy_string_node.png |
123 | | - :alt: The connection string copy button in the Connection String Only tab of the Atlas UI |
124 | | - |
125 | | - Save your connection string to a safe location. |
126 | | - |
127 | | -Connect to Your Application |
128 | | -~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
129 | | - |
130 | | -.. procedure:: |
131 | | - :style: connected |
132 | | - |
133 | | - .. step:: Create your Node.js Application |
134 | | - |
135 | | - Create a file to contain your application called ``index.js`` in your |
136 | | - project directory. Add the following code, assigning the ``uri`` |
137 | | - variable the value of your connection string. |
138 | | - |
139 | | - |
140 | | - .. code-block:: js |
141 | | - |
142 | | - const { MongoClient } = require("mongodb"); |
143 | | - |
144 | | - // Replace the uri string with your connection string. |
145 | | - const uri = |
146 | | - "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority"; |
147 | | - |
148 | | - const client = new MongoClient(uri); |
149 | | - |
150 | | - async function run() { |
151 | | - try { |
152 | | - const database = client.db('sample_mflix'); |
153 | | - const movies = database.collection('movies'); |
154 | | - |
155 | | - // Query for a movie that has the title 'Back to the Future' |
156 | | - const query = { title: 'Back to the Future' }; |
157 | | - const movie = await movies.findOne(query); |
158 | | - |
159 | | - console.log(movie); |
160 | | - } finally { |
161 | | - // Ensures that the client will close when you finish/error |
162 | | - await client.close(); |
163 | | - } |
164 | | - } |
165 | | - run().catch(console.dir); |
166 | | - |
167 | | - .. tip:: |
168 | | - |
169 | | - The preceding code example assigns the ``MongoClient`` variable using |
170 | | - :mdn:`object destructuring <Web/JavaScript/Reference/Operators/Destructuring_assignment#object_destructuring>`, |
171 | | - introduced in Node.js v6. You can create an instance of a |
172 | | - ``MongoClient`` without using object destructuring as shown in the |
173 | | - following code: |
174 | | - |
175 | | - .. code-block:: js |
176 | | - |
177 | | - const MongoClient = require("mongodb").MongoClient; |
178 | | - |
179 | | - .. step:: Run your Node.js Application |
180 | | - |
181 | | - Run the application you created from the previous step from the |
182 | | - command line: |
183 | | - |
184 | | - .. code-block:: none |
185 | | - |
186 | | - node index.js |
187 | | - |
188 | | - You should see the details of the retrieved movie document in the output: |
189 | | - |
190 | | - .. code-block:: none |
191 | | - |
192 | | - { |
193 | | - _id: ..., |
194 | | - plot: 'A young man is accidentally sent 30 years into the past...', |
195 | | - genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], |
196 | | - ... |
197 | | - title: 'Back to the Future', |
198 | | - ... |
199 | | - } |
| 25 | +MongoDB deployments. You can create your own free (no credit card |
| 26 | +required) MongoDB Atlas deployment by following the steps in this guide. |
200 | 27 |
|
201 | | - If you encounter an error or no output, check whether you specified the |
202 | | - proper connection string in the application code, and loaded the sample |
203 | | - data set in your Atlas cluster. |
| 28 | +Follow the steps in this guide to connect a sample Node.js application to |
| 29 | +a MongoDB Atlas deployment. |
204 | 30 |
|
205 | | - At this point, you should have a working application that uses |
206 | | - the {+driver-short+} to connect to your MongoDB instance, runs a query |
207 | | - on the sample data, and prints out the result. |
| 31 | +.. button:: Next: Download and Install |
| 32 | + :uri: /quick-start/download-and-install/ |
208 | 33 |
|
209 | | -Next Steps |
210 | | ----------- |
| 34 | +.. toctree:: |
211 | 35 |
|
212 | | -Learn how to read and modify data using the {+driver-short+} in our |
213 | | -:ref:`CRUD Operations <node-crud-landing>` guide or how to perform common |
214 | | -operations in our :ref:`Usage Examples <node-usage-examples>`. |
| 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/ |
0 commit comments