Skip to content

Commit 263de2a

Browse files
amalhotra-mdbamalhotra-mdb
authored
(DOCSP-43745) Connect to MongoDB (#61)
* Fill out root page for Connect to MongoDB * sample app code changes * code fixes * define client in stable api code * review changes * remove port from connection str * . * fix comments & toc tree * fix TODO comments and TOC tree * review changes * connection string fix * code highlight fix * reveal tls in toc * review code fixes * review changes
1 parent cdf7feb commit 263de2a

File tree

6 files changed

+268
-4
lines changed

6 files changed

+268
-4
lines changed

‎source/connect.txt

Lines changed: 160 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,164 @@ Connect to MongoDB
2626
/connect/stable-api
2727
/connect/connection-targets
2828
/connect/tls
29-
.. /connect/server-selection
29+
.. /connect/server-selection
3030

31-
.. TODO, the rest of this root page will be filled out in DOCSP-43745, after
32-
.. all the child pages have been created.
33-
.. This page is acting as a stub for now, so that child pages can be made.
31+
Overview
32+
--------
33+
34+
This page contains code examples that show how to use the
35+
{+driver-short+} to connect your application to MongoDB by specifying
36+
various settings.
37+
38+
.. tip:: Connection Options
39+
40+
To learn more about the connection options on this page, see the link
41+
provided in each section.
42+
43+
To use a connection example from this page, copy the code example into the
44+
:ref:`sample application <c-connect-sample>` or your own application.
45+
Be sure to replace all placeholders in the code examples, such as
46+
``<hostname>``, with the relevant values for your MongoDB deployment.
47+
48+
.. _c-connect-sample:
49+
50+
.. include:: /includes/usage-examples/sample-app-intro.rst
51+
52+
.. literalinclude:: /includes/usage-examples/connect-sample-app.c
53+
:language: c
54+
:copyable: true
55+
:linenos:
56+
:emphasize-lines: 14-16
57+
58+
Connection
59+
----------
60+
61+
The following sections describe how to connect to different targets,
62+
such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
63+
64+
Local Deployment
65+
~~~~~~~~~~~~~~~~
66+
67+
The following code shows the connection string to connect to a local
68+
instance of MongoDB:
69+
70+
.. code-block:: c
71+
72+
client = mongoc_client_new ("mongodb://localhost:27017");
73+
74+
Atlas
75+
~~~~~
76+
77+
The following code shows the connection string to connect to a
78+
deployment hosted on Atlas:
79+
80+
.. code-block:: c
81+
82+
client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?<options>");
83+
84+
Replica Set
85+
~~~~~~~~~~~
86+
87+
The following code shows the connection string to connect to a
88+
replica set:
89+
90+
.. code-block:: c
91+
92+
client = mongoc_client_new ("mongodb+srv://<replica-set-member>/?replicaSet=<replica_set_name>");
93+
94+
Transport Layer Security (TLS)
95+
------------------------------
96+
97+
The following sections describe how to connect to MongoDB
98+
while enabling the TLS protocol.
99+
100+
.. TODO, uncomment once TLS page is merged
101+
.. To learn more about using TLS with the {+driver-short+},
102+
.. see :ref:`c-tls`.
103+
104+
Enable TLS
105+
~~~~~~~~~~
106+
107+
The following tabs demonstrate how to enable TLS on a connection:
108+
109+
.. include:: /includes/connect/tls-tabs.rst
110+
111+
.. TODO, uncomment once TLS page is merged
112+
.. To learn more about enabling TLS, see :ref:`c-enable-tls` in
113+
.. the TLS configuration guide.
114+
115+
Disable Hostname Verification
116+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117+
118+
The following tabs demonstrate how to disable hostname verification when
119+
connecting by using TLS:
120+
121+
.. include:: /includes/connect/disable-host-verification-tabs.rst
122+
123+
.. TODO, uncomment once TLS page is merged
124+
.. To learn more about disabling hostname verification, see :ref:`c-certificate-revocation` in
125+
.. the TLS configuration guide.
126+
127+
Network Compression
128+
-------------------
129+
130+
The following sections describe how to connect to MongoDB
131+
while specifying network compression algorithms.
132+
133+
Compression Algorithms
134+
~~~~~~~~~~~~~~~~~~~~~~
135+
136+
The following tabs demonstrate how to specify all available compressors
137+
while connecting to MongoDB:
138+
139+
.. include:: /includes/connect/compression-tabs.rst
140+
141+
.. TODO, uncomment once TLS page is merged
142+
.. To learn more about specifying compression algorithms, see
143+
.. :ref:`c-enable-compression` in the Network Compression guide.
144+
145+
zlib Compression Level
146+
~~~~~~~~~~~~~~~~~~~~~~
147+
148+
The following tabs demonstrate how to specify a compression level for
149+
the ``zlib`` compressor:
150+
151+
.. include:: /includes/connect/zlib-level-tabs.rst
152+
153+
.. To learn more about setting the zlib compression level, see
154+
.. :ref:`c-enable-compression` in the Network Compression guide.
155+
156+
Server Selection
157+
----------------
158+
159+
The following code shows a connection string that specifies a server
160+
selection function:
161+
162+
.. code-block:: c
163+
164+
client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?server_selector=<selector_function>");
165+
166+
.. TODO, uncomment once server selection page is merged
167+
.. To learn more about customizing server selection, see
168+
.. :ref:`c-server-selection`.
169+
170+
{+stable-api+}
171+
--------------
172+
173+
The following code shows how to specify Stable API settings within a
174+
``mongoc_client_t`` instance:
175+
176+
.. code-block:: c
177+
178+
client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?<options>");
179+
180+
// Set the version of the Stable API on the client
181+
mongoc_server_api_t *api = mongoc_server_api_new(MONGOC_SERVER_API_V1);
182+
mongoc_client_set_server_api(client, api, &error);
183+
184+
// Do database work here
185+
186+
mongoc_server_api_destroy (api);
187+
188+
.. TODO, uncomment once stable API page is merged
189+
.. To learn more about the {+stable-api+}, see :ref:`c-stable-api`.

‎source/includes/connect/compression-tabs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. tabs::
2+
3+
.. tab:: Connection String
4+
:tabid: connectionstring
5+
6+
.. code-block:: c
7+
8+
client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?compressors=snappy,zlib,zstd");
9+
10+
.. tab:: MongoC URI Options
11+
:tabid: mongocurioptions
12+
13+
.. code-block:: c
14+
15+
uri = mongoc_uri_new ("mongodb://localhost:27017");
16+
mongoc_uri_set_compressors (uri, "snappy,zlib,zstd");
17+
18+
client = mongoc_client_new_from_uri (uri);

‎source/includes/connect/disable-host-verification-tabs.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. tabs::
2+
3+
.. tab:: Connection String
4+
:tabid: connectionstring
5+
6+
.. code-block:: c
7+
8+
client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?tls=true&tlsAllowInvalidHostnames=true");
9+
10+
.. tab:: MongoC URI Options
11+
:tabid: mongocurioptions
12+
13+
.. code-block:: c
14+
15+
uri = mongoc_uri_new ("mongodb://localhost:27017");
16+
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
17+
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLSALLOWINVALIDHOSTNAMES, true);
18+
19+
client = mongoc_client_new_from_uri (uri);

‎source/includes/connect/tls-tabs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. tabs::
2+
3+
.. tab:: Connection String
4+
:tabid: connectionstring
5+
6+
.. code-block:: c
7+
8+
client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?tls=true");
9+
10+
.. tab:: MongoC URI Options
11+
:tabid: mongocurioptions
12+
13+
.. code-block:: c
14+
15+
uri = mongoc_uri_new ("mongodb://localhost:27017");
16+
mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
17+
18+
client = mongoc_client_new_from_uri (uri);

‎source/includes/connect/zlib-level-tabs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. tabs::
2+
3+
.. tab:: Connection String
4+
:tabid: connectionstring
5+
6+
.. code-block:: c
7+
8+
client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?compressors=zlib&zlibCompressionLevel=<zlib_compression_level");
9+
10+
.. tab:: MongoC URI Options
11+
:tabid: mongocurioptions
12+
13+
.. code-block:: c
14+
15+
uri = mongoc_uri_new ("mongodb://localhost:27017");
16+
mongoc_uri_set_option_as_int32 (uri, MONGOC_URI_ZLIBCOMPRESSIONLEVEL, <zlib-compression-level>);
17+
18+
client = mongoc_client_new_from_uri (uri);

‎source/includes/usage-examples/connect-sample-app.c

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
#include <mongoc/mongoc.h>
2+
#include <bson/bson.h>
3+
4+
int main(void) {
5+
6+
mongoc_uri_t* uri = NULL;
7+
mongoc_client_t *client = NULL;
8+
mongoc_database_t *database = NULL;
9+
bson_t *ping = NULL, reply = BSON_INITIALIZER;
10+
bson_error_t error;
11+
12+
mongoc_init();
13+
14+
// Start example code here
15+
16+
// End example code here
17+
18+
database = mongoc_client_get_database (client, "admin");
19+
20+
ping = BCON_NEW ("ping", BCON_INT32 (1));
21+
22+
if (!mongoc_client_command_simple (client, "admin", ping, NULL, &reply, &error)) {
23+
fprintf (stderr, "%s\n", error.message);
24+
goto cleanup;
25+
}
26+
printf ("Pinged your deployment. You successfully connected to MongoDB!\n");
27+
28+
cleanup:
29+
bson_destroy (&reply);
30+
bson_destroy (ping);
31+
mongoc_database_destroy (database);
32+
mongoc_client_destroy (client);
33+
mongoc_uri_destroy (uri);
34+
mongoc_cleanup ();
35+
}

0 commit comments

Comments
 (0)