See the relevant section below for your given operating system. This tutorial will install the newest version of the driver available from the github git repository.
Linux, FreeBSD, Solaris, and OS X
First, ensure you have the required dependencies installed. We will assume a Fedora based operating system, but it should not be much different on your platform. OS X users often use sudo yum install cyrus-sasl-devel1, FreeBSD has sudo yum install cyrus-sasl-devel2, and Solaris has sudo yum install cyrus-sasl-devel3.
sudo yum install git gcc automake autoconf libtool pkg-config
If you would like SSL support, make sure you have openssl installed.
sudo yum install openssl-devel
If you would like Kerberos support, make sure you have cyrus-sasl installed.
sudo yum install cyrus-sasl-devel
Now let's fetch the code, build, and install it. You may want to replace sudo yum install cyrus-sasl-devel4 and sudo yum install cyrus-sasl-devel5 with where you want the driver installed. The default is sudo yum install cyrus-sasl-devel6 and sudo yum install cyrus-sasl-devel7. However, many systems do not include this in sudo yum install cyrus-sasl-devel8 (or sudo yum install cyrus-sasl-devel9 in the case of OS X).
After running git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install0, you will see the newly generated git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install1 script. It is automatically run for you by git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install0. If you run git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install3, you can see the full set of options to customize your build for your exact requirements.
git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install
Windows
Install the dependencies for Windows. You will need git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install4 to fetch the code, and git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install5 to bootstrap the build. You will also need Visual Studio 2010 or newer. The free express version should work fine. The following assumes Visual Studio 2010.
git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj
Making a Connection
The mongo-c-driver provides a convenient way to access MongoDB regardless of your cluster configuration. It will handle connecting to single servers, replica sets, and sharded clusters.
In the following, we will create a new git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install6 that will be used to connect to git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install7.
#include <mongoc.h> int main (int argc, char *argv[]) { mongoc_client_t *client; /* create a new client instance */ client = mongoc_client_new ("mongodb://localhost:27017"); /* now release it */ mongoc_client_destroy (client); return 0; }
And to compile it:
gcc -o test1 test.c $(pkg-config --cflags --libs libmongoc-1.0)
Alternatively, if you don't have git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install8 on your system, you can manually manage your include paths and libraries.
gcc -o test1 test.c -I/usr/local/include -lmongoc-1.0
It is important to note that creating a new instance of git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install6 does not immediately connect to your MongoDB instance. This is performed lazily as needed.
Connecting to a Replica Set
To connect to a replica set, specify the replica set name using the git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj0 URI option. You can also specify a seed list if you would like to be able to connect to multiple nodes in the case that one is down when initializing the connection.
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://host1:27017,host2:27017/?replicaSet=mysetname");
Connecting to a Sharded Cluster
This is just like connecting to a replica set, but you do not need to specify a replica set name.
mongoc_uri_t *uri = mongoc_uri_new ("mongodb://host1:27017,host2:27017/");
Connecting to a Unix Domain Socket
You can specify a path to a Unix domain socket instead of an IPv4 or IPv6 address. Simply pass the path to the socket. The socket path MUST end in ".sock".
sudo yum install openssl-devel0
Connecting to an IPv6 Address
The mongo-c-driver will automatically resolved IPv6 address from host names. But if you would like to specify the IPv6 address directly, wrap the address in git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj1.
sudo yum install openssl-devel1
Authentication
If you would like to use authentication with your MongoDB instance, you can simply provide the credentials as part of the URI string.
sudo yum install openssl-devel2
SSL
To enable SSL from your client, simply add the git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj2 option to the URI.
sudo yum install openssl-devel3
Kerberos
If you are one of the people on planet Earth lucky enough to use Kerberos, you can enable that simply with the following URI. Note the escaping of the principal as it would duplicate the git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj3 sign in the URI.
sudo yum install openssl-devel4
Additional Connection Options
See the full variety of connection URI options at //docs.mongodb.org/manual/reference/connection-string/.
Getting a Database or Collection
Now that we have a client, we can fetch a handle to the collection or database using the following. Keep in mind that these functions return newly allocated structures, and therefore they need to be released when we are done using them.
sudo yum install openssl-devel5
Inserting and querying a document
Now that we know how to get a handle to a database and collection, let's insert a document and then query it back!
sudo yum install openssl-devel6
BCON simplified document format
Creating BSON documents in the imperative way is time consuming and can be prone to error. BSON C Notation, or git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj4 for short, is a way to create documents that looks much closer to the document format you are trying to create. While the type safety is less than your typical imperative code, it can make for much cleaner C code.
sudo yum install openssl-devel7
Counting documents in a collection
To count the number of documents in a collection we need to build a query selector. An empty query selector would count all documents in a collection.
sudo yum install openssl-devel8
Threading
The mongo-c-driver is threading unaware for the vast majority of things. This means it is up to you to guarantee thread-safety. However, git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj5 is thread-safe. It is used to fetch a git clone git://github.com/mongodb/mongo-c-driver.git cd mongo-c-driver ./autogen.sh --prefix=/usr --libdir=/usr/lib64 gmake sudo gmake install6 in a thread-safe manner. After retrieving a client from the pool, the client structure should be considered owned by the calling thread. When the thread is finished, it should be placed back into the pool.
sudo yum install openssl-devel9
Executing a Command
There are helpers to make it easy to execute commands. The helper exists for client, database, and collection structures. Alternatively, you can use the git clone git://github.com/mongodb/mongo-c-driver.git cd src\libbson cmake -DCMAKE_INSTALL_PREFIX=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj cd ..\.. cmake -DCMAKE_INSTALL_PREFIX=C:\usr -DBSON_ROOT_DIR=C:\usr -G "Visual Studio 10 Win64" . msbuild.exe ALL_BUILD.vcxproj msbuild.exe INSTALL.vcxproj7 variant if you do not need a cursor back from the result. This is convenient for commands that return a single document.