1MONGOC_TUTORIAL(3) libmongoc MONGOC_TUTORIAL(3)
2
6 mongoc_tutorial - Tutorial
7 This guide offers a brief introduction to the MongoDB C Driver.
9 For more information on the C API, please refer to the API Reference.
11 Contents
13 • Tutorial
14 • Installing
16 • Starting MongoDB
18 • Include and link libmongoc in your C program
20 • Use libmongoc in a Microsoft Visual Studio Project
22 • Making a Connection
24 • Creating BSON Documents
26 • Basic CRUD Operations
28 • Executing Commands
30 • Threading
32 • Next Steps
34
36 For detailed instructions on installing the MongoDB C Driver on a par‐
37 ticular platform, please see the installation guide.
38
40 To run the examples in this tutorial, MongoDB must be installed and
41 running on localhost on the default port, 27017. To check if it is up
42 and running, connect to it with the MongoDB shell.
43 $ mongo --host localhost --port 27017
45 MongoDB shell version: 3.0.6
46 connecting to: localhost:27017/test
47 >
48
50 Include mongoc.h
51 All libmongoc's functions and types are available in one header file.
52 Simply include mongoc/mongoc.h:
53 #include <mongoc/mongoc.h>
55 CMake
57 The libmongoc installation includes a CMake config-file package, so you
58 can use CMake's find_package command to import libmongoc's CMake target
59 and link to libmongoc (as a shared library):
60 CMakeLists.txt
62 # Specify the minimum version you require.
64 find_package (mongoc-1.0 1.7 REQUIRED)
65 # The "hello_mongoc.c" sample program is shared among four tests.
67 add_executable (hello_mongoc ../../hello_mongoc.c)
68 target_link_libraries (hello_mongoc PRIVATE mongo::mongoc_shared)
69 You can also use libmongoc as a static library instead: Use the
72 mongo::mongoc_static CMake target:
73 # Specify the minimum version you require.
75 find_package (mongoc-1.0 1.7 REQUIRED)
76 # The "hello_mongoc.c" sample program is shared among four tests.
78 add_executable (hello_mongoc ../../hello_mongoc.c)
79 target_link_libraries (hello_mongoc PRIVATE mongo::mongoc_static)
80 pkg-config
83 If you're not using CMake, use pkg-config on the command line to set
84 header and library paths:
85 gcc -o hello_mongoc hello_mongoc.c $(pkg-config --libs --cflags libmongoc-1.0)
87 Or to statically link to libmongoc:
90 gcc -o hello_mongoc hello_mongoc.c $(pkg-config --libs --cflags libmongoc-static-1.0)
92 Specifying header and include paths manually
95 If you aren't using CMake or pkg-config, paths and libraries can be
96 managed manually.
97 $ gcc -o hello_mongoc hello_mongoc.c \
99 -I/usr/local/include/libbson-1.0 -I/usr/local/include/libmongoc-1.0 \
100 -lmongoc-1.0 -lbson-1.0
101 $ ./hello_mongoc
102 { "ok" : 1.000000 }
103 For Windows users, the code can be compiled and run with the following
105 commands. (This assumes that the MongoDB C Driver has been installed to
106 C:\mongo-c-driver; change the include directory as needed.)
107 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 hello_mongoc.c
109 C:\> hello_mongoc
110 { "ok" : 1.000000 }
111
113 See the libmongoc and Visual Studio guide.
114
116 Access MongoDB with a mongoc_client_t. It transparently connects to
117 standalone servers, replica sets and sharded clusters on demand. To
118 perform operations on a database or collection, create a
119 mongoc_database_t or mongoc_collection_t struct from the
120 mongoc_client_t.
121 At the start of an application, call mongoc_init() before any other
123 libmongoc functions. At the end, call the appropriate destroy function
124 for each collection, database, or client handle, in reverse order from
125 how they were constructed. Call mongoc_cleanup() before exiting.
126 The example below establishes a connection to a standalone server on
128 localhost, registers the client application as "connect-example," and
129 performs a simple command.
130 More information about database operations can be found in the CRUD Op‐
132 erations and Executing Commands sections. Examples of connecting to
133 replica sets and sharded clusters can be found on the Advanced Connec‐
134 tions page.
135 hello_mongoc.c
137 #include <mongoc/mongoc.h>
139 int
141 main (int argc, char *argv[])
142 {
143 const char *uri_string = "mongodb://localhost:27017";
144 mongoc_uri_t *uri;
145 mongoc_client_t *client;
146 mongoc_database_t *database;
147 mongoc_collection_t *collection;
148 bson_t *command, reply, *insert;
149 bson_error_t error;
150 char *str;
151 bool retval;
152 /*
154 * Required to initialize libmongoc's internals
155 */
156 mongoc_init ();
157 /*
159 * Optionally get MongoDB URI from command line
160 */
161 if (argc > 1) {
162 uri_string = argv[1];
163 }
164 /*
166 * Safely create a MongoDB URI object from the given string
167 */
168 uri = mongoc_uri_new_with_error (uri_string, &error);
169 if (!uri) {
170 fprintf (stderr,
171 "failed to parse URI: %s\n"
172 "error message: %s\n",
173 uri_string,
174 error.message);
175 return EXIT_FAILURE;
176 }
177 /*
179 * Create a new client instance
180 */
181 client = mongoc_client_new_from_uri (uri);
182 if (!client) {
183 return EXIT_FAILURE;
184 }
185 /*
187 * Register the application name so we can track it in the profile logs
188 * on the server. This can also be done from the URI (see other examples).
189 */
190 mongoc_client_set_appname (client, "connect-example");
191 /*
193 * Get a handle on the database "db_name" and collection "coll_name"
194 */
195 database = mongoc_client_get_database (client, "db_name");
196 collection = mongoc_client_get_collection (client, "db_name", "coll_name");
197 /*
199 * Do work. This example pings the database, prints the result as JSON and
200 * performs an insert
201 */
202 command = BCON_NEW ("ping", BCON_INT32 (1));
203 retval = mongoc_client_command_simple (
205 client, "admin", command, NULL, &reply, &error);
206 if (!retval) {
208 fprintf (stderr, "%s\n", error.message);
209 return EXIT_FAILURE;
210 }
211 str = bson_as_json (&reply, NULL);
213 printf ("%s\n", str);
214 insert = BCON_NEW ("hello", BCON_UTF8 ("world"));
216 if (!mongoc_collection_insert_one (collection, insert, NULL, NULL, &error)) {
218 fprintf (stderr, "%s\n", error.message);
219 }
220 bson_destroy (insert);
222 bson_destroy (&reply);
223 bson_destroy (command);
224 bson_free (str);
225 /*
227 * Release our handles and clean up libmongoc
228 */
229 mongoc_collection_destroy (collection);
230 mongoc_database_destroy (database);
231 mongoc_uri_destroy (uri);
232 mongoc_client_destroy (client);
233 mongoc_cleanup ();
234 return EXIT_SUCCESS;
236 }
237
240 Documents are stored in MongoDB's data format, BSON. The C driver uses
241 libbson to create BSON documents. There are several ways to construct
242 them: appending key-value pairs, using BCON, or parsing JSON.
243 Appending BSON
245 A BSON document, represented as a bson_t in code, can be constructed
246 one field at a time using libbson's append functions.
247 For example, to create a document like this:
249 {
251 born : ISODate("1906-12-09"),
252 died : ISODate("1992-01-01"),
253 name : {
254 first : "Grace",
255 last : "Hopper"
256 },
257 languages : [ "MATH-MATIC", "FLOW-MATIC", "COBOL" ],
258 degrees: [ { degree: "BA", school: "Vassar" }, { degree: "PhD", school: "Yale" } ]
259 }
260 Use the following code:
262 #include <bson/bson.h>
264 int
266 main (int argc,
267 char *argv[])
268 {
269 struct tm born = { 0 };
270 struct tm died = { 0 };
271 const char *lang_names[] = {"MATH-MATIC", "FLOW-MATIC", "COBOL"};
272 const char *schools[] = {"Vassar", "Yale"};
273 const char *degrees[] = {"BA", "PhD"};
274 uint32_t i;
275 char buf[16];
276 const char *key;
277 size_t keylen;
278 bson_t *document;
279 bson_t child;
280 bson_t child2;
281 char *str;
282 document = bson_new ();
284 /*
286 * Append { "born" : ISODate("1906-12-09") } to the document.
287 * Passing -1 for the length argument tells libbson to calculate the string length.
288 */
289 born.tm_year = 6; /* years are 1900-based */
290 born.tm_mon = 11; /* months are 0-based */
291 born.tm_mday = 9;
292 bson_append_date_time (document, "born", -1, mktime (&born) * 1000);
293 /*
295 * Append { "died" : ISODate("1992-01-01") } to the document.
296 */
297 died.tm_year = 92;
298 died.tm_mon = 0;
299 died.tm_mday = 1;
300 /*
302 * For convenience, this macro passes length -1 by default.
303 */
304 BSON_APPEND_DATE_TIME (document, "died", mktime (&died) * 1000);
305 /*
307 * Append a subdocument.
308 */
309 BSON_APPEND_DOCUMENT_BEGIN (document, "name", &child);
310 BSON_APPEND_UTF8 (&child, "first", "Grace");
311 BSON_APPEND_UTF8 (&child, "last", "Hopper");
312 bson_append_document_end (document, &child);
313 /*
315 * Append array of strings. Generate keys "0", "1", "2".
316 */
317 BSON_APPEND_ARRAY_BEGIN (document, "languages", &child);
318 for (i = 0; i < sizeof lang_names / sizeof (char *); ++i) {
319 keylen = bson_uint32_to_string (i, &key, buf, sizeof buf);
320 bson_append_utf8 (&child, key, (int) keylen, lang_names[i], -1);
321 }
322 bson_append_array_end (document, &child);
323 /*
325 * Array of subdocuments:
326 * degrees: [ { degree: "BA", school: "Vassar" }, ... ]
327 */
328 BSON_APPEND_ARRAY_BEGIN (document, "degrees", &child);
329 for (i = 0; i < sizeof degrees / sizeof (char *); ++i) {
330 keylen = bson_uint32_to_string (i, &key, buf, sizeof buf);
331 bson_append_document_begin (&child, key, (int) keylen, &child2);
332 BSON_APPEND_UTF8 (&child2, "degree", degrees[i]);
333 BSON_APPEND_UTF8 (&child2, "school", schools[i]);
334 bson_append_document_end (&child, &child2);
335 }
336 bson_append_array_end (document, &child);
337 /*
339 * Print the document as a JSON string.
340 */
341 str = bson_as_canonical_extended_json (document, NULL);
342 printf ("%s\n", str);
343 bson_free (str);
344 /*
346 * Clean up allocated bson documents.
347 */
348 bson_destroy (document);
349 return 0;
350 }
351 See the libbson documentation for all of the types that can be appended
353 to a bson_t.
354 Using BCON
356 BSON C Object Notation, BCON for short, is an alternative way of con‐
357 structing BSON documents in a manner closer to the intended format. It
358 has less type-safety than BSON's append functions but results in less
359 code.
360 #include <bson/bson.h>
362 int
364 main (int argc,
365 char *argv[])
366 {
367 struct tm born = { 0 };
368 struct tm died = { 0 };
369 bson_t *document;
370 char *str;
371 born.tm_year = 6;
373 born.tm_mon = 11;
374 born.tm_mday = 9;
375 died.tm_year = 92;
377 died.tm_mon = 0;
378 died.tm_mday = 1;
379 document = BCON_NEW (
381 "born", BCON_DATE_TIME (mktime (&born) * 1000),
382 "died", BCON_DATE_TIME (mktime (&died) * 1000),
383 "name", "{",
384 "first", BCON_UTF8 ("Grace"),
385 "last", BCON_UTF8 ("Hopper"),
386 "}",
387 "languages", "[",
388 BCON_UTF8 ("MATH-MATIC"),
389 BCON_UTF8 ("FLOW-MATIC"),
390 BCON_UTF8 ("COBOL"),
391 "]",
392 "degrees", "[",
393 "{", "degree", BCON_UTF8 ("BA"), "school", BCON_UTF8 ("Vassar"), "}",
394 "{", "degree", BCON_UTF8 ("PhD"), "school", BCON_UTF8 ("Yale"), "}",
395 "]");
396 /*
398 * Print the document as a JSON string.
399 */
400 str = bson_as_canonical_extended_json (document, NULL);
401 printf ("%s\n", str);
402 bson_free (str);
403 /*
405 * Clean up allocated bson documents.
406 */
407 bson_destroy (document);
408 return 0;
409 }
410 Notice that BCON can create arrays, subdocuments and arbitrary fields.
412 Creating BSON from JSON
414 For single documents, BSON can be created from JSON strings via
415 bson_new_from_json.
416 #include <bson/bson.h>
418 int
420 main (int argc,
421 char *argv[])
422 {
423 bson_error_t error;
424 bson_t *bson;
425 char *string;
426 const char *json = "{\"name\": {\"first\":\"Grace\", \"last\":\"Hopper\"}}";
428 bson = bson_new_from_json ((const uint8_t *)json, -1, &error);
429 if (!bson) {
431 fprintf (stderr, "%s\n", error.message);
432 return EXIT_FAILURE;
433 }
434 string = bson_as_canonical_extended_json (bson, NULL);
436 printf ("%s\n", string);
437 bson_free (string);
438 return 0;
440 }
441 To initialize BSON from a sequence of JSON documents, use
443 bson_json_reader_t.
444
446 This section demonstrates the basics of using the C Driver to interact
447 with MongoDB.
448 Inserting a Document
450 To insert documents into a collection, first obtain a handle to a mon‐
451 goc_collection_t via a mongoc_client_t. Then, use
452 mongoc_collection_insert_one() to add BSON documents to the collection.
453 This example inserts into the database "mydb" and collection "mycoll".
454 When finished, ensure that allocated structures are freed by using
456 their respective destroy functions.
457 #include <bson/bson.h>
459 #include <mongoc/mongoc.h>
460 #include <stdio.h>
461 int
463 main (int argc,
464 char *argv[])
465 {
466 mongoc_client_t *client;
467 mongoc_collection_t *collection;
468 bson_error_t error;
469 bson_oid_t oid;
470 bson_t *doc;
471 mongoc_init ();
473 client = mongoc_client_new ("mongodb://localhost:27017/?appname=insert-example");
475 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
476 doc = bson_new ();
478 bson_oid_init (&oid, NULL);
479 BSON_APPEND_OID (doc, "_id", &oid);
480 BSON_APPEND_UTF8 (doc, "hello", "world");
481 if (!mongoc_collection_insert_one (
483 collection, doc, NULL, NULL, &error)) {
484 fprintf (stderr, "%s\n", error.message);
485 }
486 bson_destroy (doc);
488 mongoc_collection_destroy (collection);
489 mongoc_client_destroy (client);
490 mongoc_cleanup ();
491 return 0;
493 }
494 Compile the code and run it:
496 $ gcc -o insert insert.c $(pkg-config --cflags --libs libmongoc-1.0)
498 $ ./insert
499 On Windows:
501 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 insert.c
503 C:\> insert
504 To verify that the insert succeeded, connect with the MongoDB shell.
506 $ mongo
508 MongoDB shell version: 3.0.6
509 connecting to: test
510 > use mydb
511 switched to db mydb
512 > db.mycoll.find()
513 { "_id" : ObjectId("55ef43766cb5f36a3bae6ee4"), "hello" : "world" }
514 >
515 Finding a Document
517 To query a MongoDB collection with the C driver, use the function
518 mongoc_collection_find_with_opts(). This returns a cursor to the match‐
519 ing documents. The following examples iterate through the result cur‐
520 sors and print the matches to stdout as JSON strings.
521 Use a document as a query specifier; for example,
523 { "color" : "red" }
525 will match any document with a field named "color" with value "red". An
527 empty document {} can be used to match all documents.
528 This first example uses an empty query specifier to find all documents
530 in the database "mydb" and collection "mycoll".
531 #include <bson/bson.h>
533 #include <mongoc/mongoc.h>
534 #include <stdio.h>
535 int
537 main (int argc, char *argv[])
538 {
539 mongoc_client_t *client;
540 mongoc_collection_t *collection;
541 mongoc_cursor_t *cursor;
542 const bson_t *doc;
543 bson_t *query;
544 char *str;
545 mongoc_init ();
547 client =
549 mongoc_client_new ("mongodb://localhost:27017/?appname=find-example");
550 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
551 query = bson_new ();
552 cursor = mongoc_collection_find_with_opts (collection, query, NULL, NULL);
553 while (mongoc_cursor_next (cursor, &doc)) {
555 str = bson_as_canonical_extended_json (doc, NULL);
556 printf ("%s\n", str);
557 bson_free (str);
558 }
559 bson_destroy (query);
561 mongoc_cursor_destroy (cursor);
562 mongoc_collection_destroy (collection);
563 mongoc_client_destroy (client);
564 mongoc_cleanup ();
565 return 0;
567 }
568 Compile the code and run it:
570 $ gcc -o find find.c $(pkg-config --cflags --libs libmongoc-1.0)
572 $ ./find
573 { "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }
574 On Windows:
576 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 find.c
578 C:\> find
579 { "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }
580 To look for a specific document, add a specifier to query. This example
582 adds a call to BSON_APPEND_UTF8() to look for all documents matching
583 {"hello" : "world"}.
584 #include <bson/bson.h>
586 #include <mongoc/mongoc.h>
587 #include <stdio.h>
588 int
590 main (int argc, char *argv[])
591 {
592 mongoc_client_t *client;
593 mongoc_collection_t *collection;
594 mongoc_cursor_t *cursor;
595 const bson_t *doc;
596 bson_t *query;
597 char *str;
598 mongoc_init ();
600 client = mongoc_client_new (
602 "mongodb://localhost:27017/?appname=find-specific-example");
603 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
604 query = bson_new ();
605 BSON_APPEND_UTF8 (query, "hello", "world");
606 cursor = mongoc_collection_find_with_opts (collection, query, NULL, NULL);
608 while (mongoc_cursor_next (cursor, &doc)) {
610 str = bson_as_canonical_extended_json (doc, NULL);
611 printf ("%s\n", str);
612 bson_free (str);
613 }
614 bson_destroy (query);
616 mongoc_cursor_destroy (cursor);
617 mongoc_collection_destroy (collection);
618 mongoc_client_destroy (client);
619 mongoc_cleanup ();
620 return 0;
622 }
623 $ gcc -o find-specific find-specific.c $(pkg-config --cflags --libs libmongoc-1.0)
625 $ ./find-specific
626 { "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }
627 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 find-specific.c
629 C:\> find-specific
630 { "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }
631 Updating a Document
633 This code snippet gives an example of using
634 mongoc_collection_update_one() to update the fields of a document.
635 Using the "mydb" database, the following example inserts an example
637 document into the "mycoll" collection. Then, using its _id field, the
638 document is updated with different values and a new field.
639 #include <bson/bson.h>
641 #include <mongoc/mongoc.h>
642 #include <stdio.h>
643 int
645 main (int argc, char *argv[])
646 {
647 mongoc_collection_t *collection;
648 mongoc_client_t *client;
649 bson_error_t error;
650 bson_oid_t oid;
651 bson_t *doc = NULL;
652 bson_t *update = NULL;
653 bson_t *query = NULL;
654 mongoc_init ();
656 client =
658 mongoc_client_new ("mongodb://localhost:27017/?appname=update-example");
659 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
660 bson_oid_init (&oid, NULL);
662 doc = BCON_NEW ("_id", BCON_OID (&oid), "key", BCON_UTF8 ("old_value"));
663 if (!mongoc_collection_insert_one (collection, doc, NULL, &error)) {
665 fprintf (stderr, "%s\n", error.message);
666 goto fail;
667 }
668 query = BCON_NEW ("_id", BCON_OID (&oid));
670 update = BCON_NEW ("$set",
671 "{",
672 "key",
673 BCON_UTF8 ("new_value"),
674 "updated",
675 BCON_BOOL (true),
676 "}");
677 if (!mongoc_collection_update_one (
679 collection, query, update, NULL, NULL, &error)) {
680 fprintf (stderr, "%s\n", error.message);
681 goto fail;
682 }
683 fail:
685 if (doc)
686 bson_destroy (doc);
687 if (query)
688 bson_destroy (query);
689 if (update)
690 bson_destroy (update);
691 mongoc_collection_destroy (collection);
693 mongoc_client_destroy (client);
694 mongoc_cleanup ();
695 return 0;
697 }
698 Compile the code and run it:
700 $ gcc -o update update.c $(pkg-config --cflags --libs libmongoc-1.0)
702 $ ./update
703 On Windows:
705 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 update.c
707 C:\> update
708 { "_id" : { "$oid" : "55ef43766cb5f36a3bae6ee4" }, "hello" : "world" }
709 To verify that the update succeeded, connect with the MongoDB shell.
711 $ mongo
713 MongoDB shell version: 3.0.6
714 connecting to: test
715 > use mydb
716 switched to db mydb
717 > db.mycoll.find({"updated" : true})
718 { "_id" : ObjectId("55ef549236fe322f9490e17b"), "updated" : true, "key" : "new_value" }
719 >
720 Deleting a Document
722 This example illustrates the use of mongoc_collection_delete_one() to
723 delete a document.
724 The following code inserts a sample document into the database "mydb"
726 and collection "mycoll". Then, it deletes all documents matching
727 {"hello" : "world"}.
728 #include <bson/bson.h>
730 #include <mongoc/mongoc.h>
731 #include <stdio.h>
732 int
734 main (int argc, char *argv[])
735 {
736 mongoc_client_t *client;
737 mongoc_collection_t *collection;
738 bson_error_t error;
739 bson_oid_t oid;
740 bson_t *doc;
741 mongoc_init ();
743 client =
745 mongoc_client_new ("mongodb://localhost:27017/?appname=delete-example");
746 collection = mongoc_client_get_collection (client, "test", "test");
747 doc = bson_new ();
749 bson_oid_init (&oid, NULL);
750 BSON_APPEND_OID (doc, "_id", &oid);
751 BSON_APPEND_UTF8 (doc, "hello", "world");
752 if (!mongoc_collection_insert_one (collection, doc, NULL, &error)) {
754 fprintf (stderr, "Insert failed: %s\n", error.message);
755 }
756 bson_destroy (doc);
758 doc = bson_new ();
760 BSON_APPEND_OID (doc, "_id", &oid);
761 if (!mongoc_collection_delete_one (
763 collection, doc, NULL, NULL, &error)) {
764 fprintf (stderr, "Delete failed: %s\n", error.message);
765 }
766 bson_destroy (doc);
768 mongoc_collection_destroy (collection);
769 mongoc_client_destroy (client);
770 mongoc_cleanup ();
771 return 0;
773 }
774 Compile the code and run it:
776 $ gcc -o delete delete.c $(pkg-config --cflags --libs libmongoc-1.0)
778 $ ./delete
779 On Windows:
781 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 delete.c
783 C:\> delete
784 Use the MongoDB shell to prove that the documents have been removed
786 successfully.
787 $ mongo
789 MongoDB shell version: 3.0.6
790 connecting to: test
791 > use mydb
792 switched to db mydb
793 > db.mycoll.count({"hello" : "world"})
794 0
795 >
796 Counting Documents
798 Counting the number of documents in a MongoDB collection is similar to
799 performing a find operation. This example counts the number of docu‐
800 ments matching {"hello" : "world"} in the database "mydb" and collec‐
801 tion "mycoll".
802 #include <bson/bson.h>
804 #include <mongoc/mongoc.h>
805 #include <stdio.h>
806 int
808 main (int argc, char *argv[])
809 {
810 mongoc_client_t *client;
811 mongoc_collection_t *collection;
812 bson_error_t error;
813 bson_t *doc;
814 int64_t count;
815 mongoc_init ();
817 client =
819 mongoc_client_new ("mongodb://localhost:27017/?appname=count-example");
820 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
821 doc = bson_new_from_json (
822 (const uint8_t *) "{\"hello\" : \"world\"}", -1, &error);
823 count = mongoc_collection_count (
825 collection, MONGOC_QUERY_NONE, doc, 0, 0, NULL, &error);
826 if (count < 0) {
828 fprintf (stderr, "%s\n", error.message);
829 } else {
830 printf ("%" PRId64 "\n", count);
831 }
832 bson_destroy (doc);
834 mongoc_collection_destroy (collection);
835 mongoc_client_destroy (client);
836 mongoc_cleanup ();
837 return 0;
839 }
840 Compile the code and run it:
842 $ gcc -o count count.c $(pkg-config --cflags --libs libmongoc-1.0)
844 $ ./count
845 1
846 On Windows:
848 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 count.c
850 C:\> count
851 1
852
854 The driver provides helper functions for executing MongoDB commands on
855 client, database and collection structures. The _simple variants return
856 booleans indicating success or failure.
857 This example executes the ping command against the database "mydb".
859 #include <bson/bson.h>
861 #include <mongoc/mongoc.h>
862 #include <stdio.h>
863 int
865 main (int argc, char *argv[])
866 {
867 mongoc_client_t *client;
868 bson_error_t error;
869 bson_t *command;
870 bson_t reply;
871 char *str;
872 mongoc_init ();
874 client = mongoc_client_new (
876 "mongodb://localhost:27017/?appname=executing-example");
877 command = BCON_NEW ("ping", BCON_INT32 (1));
879 if (mongoc_client_command_simple (
880 client, "mydb", command, NULL, &reply, &error)) {
881 str = bson_as_canonical_extended_json (&reply, NULL);
882 printf ("%s\n", str);
883 bson_free (str);
884 } else {
885 fprintf (stderr, "Failed to run command: %s\n", error.message);
886 }
887 bson_destroy (command);
889 bson_destroy (&reply);
890 mongoc_client_destroy (client);
891 mongoc_cleanup ();
892 return 0;
894 }
895 Compile the code and run it:
898 $ gcc -o executing executing.c $(pkg-config --cflags --libs libmongoc-1.0)
900 $ ./executing
901 { "ok" : { "$numberDouble" : "1.0" }, "$clusterTime" : { "clusterTime" : { "$timestamp" : { "t" : 1682609211, "i" : 1 } }, "signature" : { "hash" : { "$binary" : { "base64" : "AAAAAAAAAAAAAAAAAAAAAAAAAAA=", "subType" : "00" } }, "keyId" : { "$numberLong" : "0" } } }, "operationTime" : { "$timestamp" : { "t" : 1682609211, "i" : 1 } } }
902 On Windows:
904 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 executing.c
906 C:\> executing
907 { "ok" : { "$numberDouble" : "1.0" }, "$clusterTime" : { "clusterTime" : { "$timestamp" : { "t" : 1682609211, "i" : 1 } }, "signature" : { "hash" : { "$binary" : { "base64" : "AAAAAAAAAAAAAAAAAAAAAAAAAAA=", "subType" : "00" } }, "keyId" : { "$numberLong" : "0" } } }, "operationTime" : { "$timestamp" : { "t" : 1682609211, "i" : 1 } } }
908
910 The MongoDB C Driver is thread-unaware in the vast majority of its op‐
911 erations. This means it is up to the programmer to guarantee
912 thread-safety.
913 However, mongoc_client_pool_t is thread-safe and is used to fetch a
915 mongoc_client_t in a thread-safe manner. After retrieving a client from
916 the pool, the client structure should be considered owned by the call‐
917 ing thread. When the thread is finished, the client should be placed
918 back into the pool.
919 example-pool.c
921 /* gcc example-pool.c -o example-pool $(pkg-config --cflags --libs
923 * libmongoc-1.0) */
924 /* ./example-pool [CONNECTION_STRING] */
926 #include <mongoc/mongoc.h>
928 #include <pthread.h>
929 #include <stdio.h>
930 static pthread_mutex_t mutex;
932 static bool in_shutdown = false;
933 static void *
935 worker (void *data)
936 {
937 mongoc_client_pool_t *pool = data;
938 mongoc_client_t *client;
939 bson_t ping = BSON_INITIALIZER;
940 bson_error_t error;
941 bool r;
942 BSON_APPEND_INT32 (&ping, "ping", 1);
944 while (true) {
946 client = mongoc_client_pool_pop (pool);
947 /* Do something with client. If you are writing an HTTP server, you
948 * probably only want to hold onto the client for the portion of the
949 * request performing database queries.
950 */
951 r = mongoc_client_command_simple (
952 client, "admin", &ping, NULL, NULL, &error);
953 if (!r) {
955 fprintf (stderr, "%s\n", error.message);
956 }
957 mongoc_client_pool_push (pool, client);
959 pthread_mutex_lock (&mutex);
961 if (in_shutdown || !r) {
962 pthread_mutex_unlock (&mutex);
963 break;
964 }
965 pthread_mutex_unlock (&mutex);
967 }
968 bson_destroy (&ping);
970 return NULL;
971 }
972 int
974 main (int argc, char *argv[])
975 {
976 const char *uri_string = "mongodb://127.0.0.1/?appname=pool-example";
977 mongoc_uri_t *uri;
978 bson_error_t error;
979 mongoc_client_pool_t *pool;
980 pthread_t threads[10];
981 unsigned i;
982 void *ret;
983 pthread_mutex_init (&mutex, NULL);
985 mongoc_init ();
986 if (argc > 1) {
988 uri_string = argv[1];
989 }
990 uri = mongoc_uri_new_with_error (uri_string, &error);
992 if (!uri) {
993 fprintf (stderr,
994 "failed to parse URI: %s\n"
995 "error message: %s\n",
996 uri_string,
997 error.message);
998 return EXIT_FAILURE;
999 }
1000 pool = mongoc_client_pool_new (uri);
1002 mongoc_client_pool_set_error_api (pool, 2);
1003 for (i = 0; i < 10; i++) {
1005 pthread_create (&threads[i], NULL, worker, pool);
1006 }
1007 sleep (10);
1009 pthread_mutex_lock (&mutex);
1010 in_shutdown = true;
1011 pthread_mutex_unlock (&mutex);
1012 for (i = 0; i < 10; i++) {
1014 pthread_join (threads[i], &ret);
1015 }
1016 mongoc_client_pool_destroy (pool);
1018 mongoc_uri_destroy (uri);
1019 mongoc_cleanup ();
1021 return EXIT_SUCCESS;
1023 }
1024
1027 To find information on advanced topics, browse the rest of the C driver
1028 guide or the official MongoDB documentation.
1029 For help with common issues, consult the Troubleshooting page. To re‐
1031 port a bug or request a new feature, follow these instructions.
1032
1034 MongoDB, Inc
1035
1037 2017-present, MongoDB, Inc
10381.24.3 Aug 17, 2023 MONGOC_TUTORIAL(3)