Installing MongoDB through the Repositories

Repositories are basically online directories filled with software. Every package contains information about the version number, prerequisites, and possible incompatibilities. This information is useful when you need to install a software package that requires another piece of software to be installed first because the prerequisites can be installed at the same time.

The default repositories available in Ubuntu (and other Debian-based distributions) contain MongoDB, but they may be out-of-date versions of the software. Therefore, let’s tell apt-get (the software you use to install software from repositories) to look at a custom repository. To do this, you need to add the following line to your repository-list (/etc/apt/sources.list):

deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen

Next, you need to import 10gen’s public GPG key, used to sign the packages, ensuring their consistency; you can do so by using the apt-key command:

$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

When that is done, you need to tell apt-get that it contains new repositories; you can do so using apt-get’s update command:

$ sudo apt-get update

This line made aptitude aware of your manually added repository. This means you can now tell apt-get to install the software itself. You do this by typing the following command in the shell:

$ sudo apt-get install mongodb-10gen

This line installs the current stable (production) version from MongoDB. If you wish to install any other version from MongoDB instead, you need to specify the version number. For example, to install the current unstable (development) version from MongoDB, type in the following command instead:

$ sudo apt-get install mongodb-10gen=2.5.0

That’s all there is to it. At this point, MongoDB has been installed and is (almost) ready to use!

echo "mongodb-10gen hold" | sudo dpkg --set-selections

Installing MongoDB Manually

Next, we’ll cover how to install MongoDB manually. Given how easy it is to install MongoDB with aptitude automatically, you might wonder why you would want to install the software manually. For starters, not all Linux distributions use apt-get. Sure, many of them do (including primarily the ones that are based on Debian Linux), but some don’t. Also, the packaging remains a work in progress, so it might be the case that there are versions not yet available through the repositories. It’s also possible that the version of MongoDB you want to use isn’t included in the repository. Installing the software manually also gives you the ability to run multiple versions of MongoDB at the same time.

You’ve decided which version of MongoDB you would like to use, and you’ve downloaded it from their website, http://mongodb.org/downloads, to your Home directory. Next, you need to extract the package with the following command:

$ tar xzf mongodb-linux-x86_64-latest.tgz

This command extracts the entire contents of the package to a new directory called mongodb-linux-x86_64-xxxx-yy-zz; this directory is located under your current directory. This directory will contain a number of subdirectories and files. The directory that contains the executable files is called the bin directory. We will cover which applications perform which tasks shortly.

However, you don’t need to do anything further to install the application. Indeed, it doesn’t take much more time to install MongoDB manually—depending on what else you need to install, it might even be faster. Manually installing MongoDB does have some downsides, however. For example, the executables that you just extracted and found in the bin directory can’t be executed from anywhere except the bin directory by default. Thus, if you want to run the mongod service, you will need to do so directly from the aforementioned bin directory. This downside highlights one of the benefits of installing MongoDB through repositories.

Getting MongoDB for PHP

Like MongoDB, PHP is a cross-platform development tool, and the steps required to set up MongoDB in PHP vary depending on the intended platform. Previously, this chapter showed you how to install MongoDB on both Ubuntu and Windows; we’ll adopt the same approach here, demonstrating how to install the driver for PHP on both Ubuntu and Windows.

Begin by downloading the PHP driver for your operating system. Do this by firing up your browser and navigating to www.mongodb.org. At the time of writing, the website includes a separate menu option called Drivers. Click this option to bring up a list of currently available language drivers (see Figure 2-2).

Next, select PHP from the list of languages and follow the links to download the latest (stable) version of the driver. Different operating systems will require different approaches for installing the MongoDB extension for PHP automatically. That’s right; just as you were able to install MongoDB on Ubuntu automatically, you can do the same for the PHP driver. And just as when installing MongoDB under Ubuntu, you can also choose to install the PHP language driver manually. Let’s look at the two options available to you.

Installing the PHP Driver on Unix-Based Platforms Automatically

The developers of PHP came up with a great solution that allows you to expand your PHP installation with other popular extensions: PECL. PECL is a repository solely designed for PHP; it provides a directory of all known extensions that you can use to download, install, and even develop PHP extensions. If you are already acquainted with the package-management system called aptitude (which you used previously to install MongoDB), then you will be pleased by how similar PECL’s interface is to the one in aptitude.

Assuming that you have PECL installed on your system, open up a console and type the following command to install the MongoDB extension:

$ sudo pecl install mongo

Entering this command causes PECL to download and install the MongoDB extension for PHP automatically. In other words, PECL will download the extension for your PHP version and place it in the PHP extensions directory. There’s just one catch: PECL does not automatically add the extension to the list of loaded extensions; you will need to do this step manually. To do so, open a text editor (vim, nano, or whichever text editor you prefer) and alter the file called php.ini, which is the main configuration file PHP uses to control its behavior, including the extensions it should load.

Next, open the php.ini file, scroll down to the extensions section, and add the following line to tell PHP to load the MongoDB driver:

extension=mongo.so

The “Confirming That Your PHP Installation Works” section later in this chapter will cover how to confirm that an extension has been loaded successfully.

That’s all, folks! You’ve just installed the MongoDB extension for your PHP installation, and you are now ready to use it. Next, you will learn how to install the driver manually.

Installing the PHP Driver on Unix-Based Platforms Manually

If you would prefer to compile the driver yourself or for some reason are unable to use the PECL application as described previously (your hosting provider might not support this option, for instance), then you can also choose to download the source driver and compile it manually.

To download the driver, go to the github website (http://github.com). This site offers the latest source package for the PHP driver. Once you download it, you will need to extract the package, and make the driver by running the following set of commands:

$ tar zxvf mongodb-mongdb-php-driver-<commit_id>.tar.gz
$ cd mongodb-mongodb-php-driver-<commit_id>
$ phpize
$ ./configure
$ sudo make install

This process can take a while, depending on the speed of your system. Once the process completes, your MongoDB PHP driver is installed and ready to use! After you execute the commands, you will be shown where the driver has been placed; typically, the output looks something like this:

Installing '/ usr/lib/php/extensions/no-debug-zts-20060613/mongo.so'

You do need to confirm that this directory is the same directory where PHP stores its extensions by default. You can use the following command to confirm where PHP stores its extensions:

$ php -i | grep extension_dir

This line outputs the directory where all PHP extensions should be placed. If this directory doesn’t match the one where the mongo.so driver was placed, then you must move the mongo.so driver to the proper directory, so PHP knows where to find it.

As before, you will need to tell PHP that the newly created extension has been placed in its extension directory, and that it should load this extension. You can specify this by modifying the php.ini file’s extensions section; add the following line to that section:

extension=mongo.so

Finally, a restart of your web service is required. When using the Apache HTTPd service, you can accomplish this using the following service command:

sudo /etc/init.d/apache2 restart

That’s it! This process is a little lengthier than using PECL’s automated method; however, if you are unable to use PECL, or if you are a driver developer and interested in bug fixes, then you would want to use the manual method instead.

Installing the PHP Driver on Windows

You have seen previously how to install MongoDB on your Windows operating system. Now let’s look at how to implement the MongoDB driver for PHP on Windows.

For Windows , there are precompiled binaries available for each release of the PHP driver for MongoDB. You can get these binaries from the previously mentioned github website (http://github.com). The biggest challenge in this case is choosing the correct package to install for your version of PHP (a wide variety of packages are available). If you aren’t certain which package version you need, you can use the <? phpinfo(); ?> command in a PHP page to learn exactly which one suits your specific environment. We’ll take a closer look at the phpinfo() command in the next section.

After downloading the correct package and extracting its contents, all you need to do is copy the driver file (called php_mongo.dll) to your PHP’s extension directory; this enables PHP to pick it up.

Depending on your version of PHP, the extension directory may be called either Ext or Extensions. If you aren’t certain which directory it should be, you can review the PHP documentation that came with the version of PHP installed on your system.

Once you place the driver DLL into the PHP extensions directory, you still need to tell PHP to load the driver. Do this by altering the php.ini file and adding the following line in the extensions section:

extension=php_mongo.dll

When done, restart the HTTP service on your system, and you are now ready to use the MongoDB driver in PHP. Before you start leveraging the magic of MongoDB with PHP, however, you need to confirm that the extension is loaded correctly.

Connecting to and Disconnecting from the PHP Driver

You’ve confirmed that the MongoDB PHP driver has been loaded correctly, so it’s time to start writing some PHP code! Let’s take a look at two simple yet fundamental options for working with MongoDB: initiating a connection between MongoDB and PHP, and then severing that connection.

You use the Mongo class to initiate a connection between MongoDB and PHP; this same class also lets you use the database server commands. A simple yet typical connection command looks like this:

$connection = new Mongo();

If you use this command without providing any parameters, it will connect to the MongoDB service on the default MongoDB port (27017) on your localhost. If your MongoDB service is running somewhere else, then you simply specify the hostname of the remote host you want to connect to:

$connection = new Mongo(" example.com ");

This line instantiates a fresh connection for your MongoDB service running on the server and listening to the example.com domain name (note that it will still connect to the default port: 27017). If you want to connect to a different port number, however (for example, if you don’t want to use the default port, or you’re already running another session of the MongoDB service on that port), you can do so by specifying the port number and hostname:

$connection = new Mongo(" example.com:12345 ");

This example creates a connection to the database service. Next, you will learn how to disconnect from the service. Assuming you used the method just described to connect to your database, you can call $connection again to pass the close() command to terminate the connection, as in this example:

$connection->close();

The close doesn’t need to be called, except in unusual circumstances. The reason for this is that the PHP driver closes the connection to the database once the Mongo object goes out of scope. Nevertheless, it is recommended that you call close() at the end of your PHP code; this helps you avoid keeping old connections from hanging around until they eventually time out. It also helps you ensure that any existing connection is closed, thereby enabling a new connection to happen, as in the following example:

$connection = new Mongo();
$connection->close();
$connection->connect();

The following snippet shows how this would look like in PHP:

<?php
  
// Establish the database connection
$connection = new Mongo()
  
// Close the database connection
$connection->close();
  
?>

Installing PyMongo under Linux

Python offers a specific package for MongoDB support called PyMongo . This package allows you to interact with the MongoDB database, but you will need to get this driver up and running before you can use this powerful combination. As when installing the PHP driver, there are two methods you can use to install PyMongo: an automated approach that relies on setuptools or a manual approach where you download the source code for the project. The following sections show you how to install PyMongo using both approaches.

$ sudo apt-get install python-pip

$ sudo pip install pymongo

$ wget http://pypi.python.org/packages/source/p/pymongo/pymongo-2.5.1.tar.gz
$ tar xzf pymongo-2.5.1.tar.gz

$ cd pymongo-2.5.1
$ sudo python setup.py install

Installing PyMongo under Windows

Installing PyMongo under Windows is a straightforward process. As when installing PyMongo under Linux, Easy Install can simplify installing PyMongo under Windows as well. If you don’t have setuptools installed yet (this package includes the easy_install command), then go to the Python Package Index website (http://pypi.python.org) to locate the setuptools installer.

For example, assume you have Python version 2.7.5 installed on your system. You will need to download the setuptools package for v2.7.x. The good news is that you don’t need to compile any of this; rather, you can simply download the appropriate package and double-click the executable to install setuptools on your system! It is that simple.

Once the installation is complete, you will find the easy_install.exe file in Python’s Scripts subdirectory. At this point, you’re ready to install PyMongo on Windows.

Once you’ve successfully installed setuptools, you can open a command prompt and cd your way to Python’s Scripts directory. By default, this is set to C:Pythonxy Scripts, where xy represents your version number. Once you navigate to this location, you can use the same syntax shown previously for installing the Unix variant:

C:Python27Scripts> easy_install PyMongo

Unlike the output that you get when installing this program on a Linux machine, the output here is rather brief, indicating only that the extension has been downloaded and installed (see Figure 2-4). That said, this information is sufficient for your purposes in this case.