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. These functions return
856 cursors; the _simple variants return booleans indicating success or
857 failure.
858 This example executes the collStats command against the collection "my‐
860 coll" in database "mydb".
861 #include <bson/bson.h>
863 #include <mongoc/mongoc.h>
864 #include <stdio.h>
865 int
867 main (int argc, char *argv[])
868 {
869 mongoc_client_t *client;
870 mongoc_collection_t *collection;
871 bson_error_t error;
872 bson_t *command;
873 bson_t reply;
874 char *str;
875 mongoc_init ();
877 client = mongoc_client_new (
879 "mongodb://localhost:27017/?appname=executing-example");
880 collection = mongoc_client_get_collection (client, "mydb", "mycoll");
881 command = BCON_NEW ("collStats", BCON_UTF8 ("mycoll"));
883 if (mongoc_collection_command_simple (
884 collection, command, NULL, &reply, &error)) {
885 str = bson_as_canonical_extended_json (&reply, NULL);
886 printf ("%s\n", str);
887 bson_free (str);
888 } else {
889 fprintf (stderr, "Failed to run command: %s\n", error.message);
890 }
891 bson_destroy (command);
893 bson_destroy (&reply);
894 mongoc_collection_destroy (collection);
895 mongoc_client_destroy (client);
896 mongoc_cleanup ();
897 return 0;
899 }
900 Compile the code and run it:
902 $ gcc -o executing executing.c $(pkg-config --cflags --libs libmongoc-1.0)
904 $ ./executing
905 { "ns" : "mydb.mycoll", "count" : 1, "size" : 48, "avgObjSize" : 48, "numExtents" : 1, "storageSize" : 8192,
906 "lastExtentSize" : 8192.000000, "paddingFactor" : 1.000000, "userFlags" : 1, "capped" : false, "nindexes" : 1,
907 "indexDetails" : { }, "totalIndexSize" : 8176, "indexSizes" : { "_id_" : 8176 }, "ok" : 1.000000 }
908 On Windows:
910 C:\> cl.exe /IC:\mongo-c-driver\include\libbson-1.0 /IC:\mongo-c-driver\include\libmongoc-1.0 executing.c
912 C:\> executing
913 { "ns" : "mydb.mycoll", "count" : 1, "size" : 48, "avgObjSize" : 48, "numExtents" : 1, "storageSize" : 8192,
914 "lastExtentSize" : 8192.000000, "paddingFactor" : 1.000000, "userFlags" : 1, "capped" : false, "nindexes" : 1,
915 "indexDetails" : { }, "totalIndexSize" : 8176, "indexSizes" : { "_id_" : 8176 }, "ok" : 1.000000 }
916
918 The MongoDB C Driver is thread-unaware in the vast majority of its op‐
919 erations. This means it is up to the programmer to guarantee
920 thread-safety.
921 However, mongoc_client_pool_t is thread-safe and is used to fetch a
923 mongoc_client_t in a thread-safe manner. After retrieving a client from
924 the pool, the client structure should be considered owned by the call‐
925 ing thread. When the thread is finished, the client should be placed
926 back into the pool.
927 example-pool.c
929 /* gcc example-pool.c -o example-pool $(pkg-config --cflags --libs
931 * libmongoc-1.0) */
932 /* ./example-pool [CONNECTION_STRING] */
934 #include <mongoc/mongoc.h>
936 #include <pthread.h>
937 #include <stdio.h>
938 static pthread_mutex_t mutex;
940 static bool in_shutdown = false;
941 static void *
943 worker (void *data)
944 {
945 mongoc_client_pool_t *pool = data;
946 mongoc_client_t *client;
947 bson_t ping = BSON_INITIALIZER;
948 bson_error_t error;
949 bool r;
950 BSON_APPEND_INT32 (&ping, "ping", 1);
952 while (true) {
954 client = mongoc_client_pool_pop (pool);
955 /* Do something with client. If you are writing an HTTP server, you
956 * probably only want to hold onto the client for the portion of the
957 * request performing database queries.
958 */
959 r = mongoc_client_command_simple (
960 client, "admin", &ping, NULL, NULL, &error);
961 if (!r) {
963 fprintf (stderr, "%s\n", error.message);
964 }
965 mongoc_client_pool_push (pool, client);
967 pthread_mutex_lock (&mutex);
969 if (in_shutdown || !r) {
970 pthread_mutex_unlock (&mutex);
971 break;
972 }
973 pthread_mutex_unlock (&mutex);
975 }
976 bson_destroy (&ping);
978 return NULL;
979 }
980 int
982 main (int argc, char *argv[])
983 {
984 const char *uri_string = "mongodb://127.0.0.1/?appname=pool-example";
985 mongoc_uri_t *uri;
986 bson_error_t error;
987 mongoc_client_pool_t *pool;
988 pthread_t threads[10];
989 unsigned i;
990 void *ret;
991 pthread_mutex_init (&mutex, NULL);
993 mongoc_init ();
994 if (argc > 1) {
996 uri_string = argv[1];
997 }
998 uri = mongoc_uri_new_with_error (uri_string, &error);
1000 if (!uri) {
1001 fprintf (stderr,
1002 "failed to parse URI: %s\n"
1003 "error message: %s\n",
1004 uri_string,
1005 error.message);
1006 return EXIT_FAILURE;
1007 }
1008 pool = mongoc_client_pool_new (uri);
1010 mongoc_client_pool_set_error_api (pool, 2);
1011 for (i = 0; i < 10; i++) {
1013 pthread_create (&threads[i], NULL, worker, pool);
1014 }
1015 sleep (10);
1017 pthread_mutex_lock (&mutex);
1018 in_shutdown = true;
1019 pthread_mutex_unlock (&mutex);
1020 for (i = 0; i < 10; i++) {
1022 pthread_join (threads[i], &ret);
1023 }
1024 mongoc_client_pool_destroy (pool);
1026 mongoc_uri_destroy (uri);
1027 mongoc_cleanup ();
1029 return EXIT_SUCCESS;
1031 }
1032
1035 To find information on advanced topics, browse the rest of the C driver
1036 guide or the official MongoDB documentation.
1037 For help with common issues, consult the Troubleshooting page. To re‐
1039 port a bug or request a new feature, follow these instructions.
1040
1042 MongoDB, Inc
1043
1045 2017-present, MongoDB, Inc
10461.23.1 Oct 20, 2022 MONGOC_TUTORIAL(3)