(DOCSP-43745) Connect to MongoDB

source/connect.txt

@@ -26,8 +26,169 @@
    /connect/stable-api
    /connect/connection-targets
    /connect/tls
-..   /connect/server-selection
+.. /connect/server-selection
 
-.. TODO, the rest of this root page will be filled out in DOCSP-43745, after
-.. all the child pages have been created. 
-.. This page is acting as a stub for now, so that child pages can be made.
+Overview
+--------
+
+This page contains code examples that show how to use the
+{+driver-short+} to connect your application to MongoDB by specifying
+various settings. 
+
+.. tip:: Connection Options
+
+   To learn more about the connection options on this page, see the link
+   provided in each section.
+
+To use a connection example from this page, copy the code example into the
+:ref:`sample application <c-connect-sample>` or your own application.
+Be sure to replace all placeholders in the code examples, such as
+``<hostname>``, with the relevant values for your MongoDB deployment.
+
+.. _c-connect-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/connect-sample-app.c
+   :language: c
+   :copyable: true
+   :linenos:
+   :emphasize-lines: 14-16
+
+Connection
+----------
+
+The following sections describe how to connect to different targets,
+such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
+
+Local Deployment
+~~~~~~~~~~~~~~~~
+
+The following code shows the connection string to connect to a local
+instance of MongoDB:
+
+.. code-block:: c
+
+   uri = mongoc_uri_new ("mongodb://localhost:27017"); 
+   client = mongoc_client_new_from_uri (uri);
+
+Atlas
+~~~~~
+
+The following code shows the connection string to connect to a
+deployment hosted on Atlas:
+
+.. code-block:: c
+
+   uri = "mongodb+srv://<db_username>:<db_password>@<hostname>/?<options>";
+   client = mongoc_client_new (uri);
+
+Replica Set
+~~~~~~~~~~~
+
+The following code shows the connection string to connect to a
+replica set:
+
+.. code-block:: c
+
+   uri = "mongodb+srv://<replica-set-member>/?replicaSet=<replica_set_name>";
+   client = mongoc_client_new (uri);
+
+Transport Layer Security (TLS)
+------------------------------
+
+The following sections describe how to connect to MongoDB
+while enabling the TLS protocol. 
+
+.. TODO, uncomment once TLS page is merged
+.. To learn more about using TLS with the {+driver-short+},
+.. see :ref:`c-tls`.
+
+Enable TLS
+~~~~~~~~~~
+
+The following tabs demonstrate how to enable TLS on a connection:
+
+.. include:: /includes/connect/tls-tabs.rst
+
+.. TODO, uncomment once TLS page is merged
+.. To learn more about enabling TLS, see :ref:`c-enable-tls` in
+.. the TLS configuration guide.
+
+Disable Hostname Verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to disable hostname verification when
+connecting by using TLS:
+
+.. include:: /includes/connect/disable-host-verification-tabs.rst
+
+.. TODO, uncomment once TLS page is merged
+.. To learn more about disabling hostname verification, see :ref:`c-certificate-revocation` in
+.. the TLS configuration guide.
+
+Network Compression
+-------------------
+
+The following sections describe how to connect to MongoDB
+while specifying network compression algorithms.
+
+Compression Algorithms
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify all available compressors
+while connecting to MongoDB:
+
+.. include:: /includes/connect/compression-tabs.rst
+
+.. TODO, uncomment once TLS page is merged
+.. To learn more about specifying compression algorithms, see
+.. :ref:`c-enable-compression` in the Network Compression guide.
+
+zlib Compression Level
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify a compression level for
+the ``zlib`` compressor:
+
+.. include:: /includes/connect/zlib-level-tabs.rst
+
+.. To learn more about setting the zlib compression level, see
+.. :ref:`c-enable-compression` in the Network Compression guide.
+
+Server Selection
+----------------
+
+The following code shows a connection string that specifies a server
+selection function:
+
+.. code-block:: c
+
+   client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?server_selector=<selector_function>");
+
+.. TODO, uncomment once server selection page is merged
+.. To learn more about customizing server selection, see
+.. :ref:`c-server-selection`.
+
+{+stable-api+}
+--------------
+
+The following code shows how to specify Stable API settings within a
+``mongoc_client_t`` instance:
+
+.. code-block:: c 
+
+   bson_error_t error;
+
+   client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?<options>");
+
+   // Set the version of the Stable API on the client
+   mongoc_server_api_t *api = mongoc_server_api_new(MONGOC_SERVER_API_V1);
+   mongoc_client_set_server_api(client, api, &error)
+
+   // Do database work here
+
+   mongoc_server_api_destroy (api);
+
+.. TODO, uncomment once stable API page is merged
+.. To learn more about the {+stable-api+}, see :ref:`c-stable-api`.

source/includes/connect/compression-tabs.rst

@@ -0,0 +1,18 @@
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: c
+
+         client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?compressors=snappy,zlib,zstd");
+
+   .. tab:: MongoC URI Options
+      :tabid: mongocurioptions
+
+      .. code-block:: c
+
+         uri = mongoc_uri_new ("mongodb://localhost:27017");  
+         mongoc_uri_set_compressors (uri, "snappy,zlib,zstd");
+
+         client = mongoc_client_new_from_uri (uri);

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

@@ -0,0 +1,19 @@
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: c
+
+         client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?tls=true&tlsAllowInvalidHostnames=true");
+
+   .. tab:: MongoC URI Options
+      :tabid: mongocurioptions
+
+      .. code-block:: c
+
+         uri = mongoc_uri_new ("mongodb://localhost:27017");  
+         mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
+         mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLSALLOWINVALIDHOSTNAMES, true);
+
+         client = mongoc_client_new_from_uri (uri);

source/includes/connect/tls-tabs.rst

@@ -0,0 +1,18 @@
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: c
+
+         client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?tls=true");
+
+   .. tab:: MongoC URI Options
+      :tabid: mongocurioptions
+
+      .. code-block:: c
+
+         uri = mongoc_uri_new ("mongodb://localhost:27017");  
+         mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
+
+         client = mongoc_client_new_from_uri (uri);

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

@@ -0,0 +1,18 @@
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: c
+
+         client = mongoc_client_new("mongodb://<db_username>:<db_password>@<hostname>/?compressors=zlib&zlibCompressionLevel=<zlib_compression_level");
+
+   .. tab:: MongoC URI Options
+      :tabid: mongocurioptions
+
+      .. code-block:: c
+
+         uri = mongoc_uri_new ("mongodb://localhost:27017");  
+         mongoc_uri_set_option_as_int32 (uri, MONGOC_URI_ZLIBCOMPRESSIONLEVEL, <zlib-compression-level>);
+
+         client = mongoc_client_new_from_uri (uri);

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

@@ -0,0 +1,35 @@
+#include <mongoc/mongoc.h>
+#include <bson/bson.h>
+
+int main(void) {
+
+  mongoc_uri_t* uri = NULL;
+  mongoc_client_t *client = NULL;
+  mongoc_database_t *database = NULL;
+  bson_t *ping = NULL, reply = BSON_INITIALIZER;
+  bson_error_t error;
+
+  mongoc_init();
+
+  // Start example code here
+
+  // End example code here
+
+  database = mongoc_client_get_database (client, "admin");
+
+  ping = BCON_NEW ("ping", BCON_INT32 (1));
+
+  if (!mongoc_client_command_simple (client, "admin", ping, NULL, &reply, &error)) {
+    fprintf (stderr, "%s\n", error.message);
+    goto cleanup;
+  }
+  printf ("Pinged your deployment. You successfully connected to MongoDB!\n");
+
+  cleanup:
+    bson_destroy (&reply);
+    bson_destroy (ping);
+    mongoc_database_destroy (database);
+    mongoc_client_destroy (client);
+    mongoc_uri_destroy (uri);
+    mongoc_cleanup ();
+}