In this post, I’ll show you how to install and configure MongoChef and the necessary MongoDB tools to get you started with IntelliShell and enjoy the richest MongoDB editing experience currently available for Windows, Mac and Linux.
Everybody ready? Then let’s go!
Install 3T MongoChef
First of all, let’s download MongoChef! It’s available at http://3t.io/mongochef
Here, you can download MongoChef for your particular platform and ‘bitness’. For example, if you wish to download the 64-bit Windows version, click on ‘Download (64-bit)’ in the ‘WINDOWS’ section. Or if you wished to download the 32-bit Windows version, you would click on the ‘Download for 32-bit systems’ link at the bottom of the ‘WINDOWS’ section. Likewise for Linux, but this time in the rightmost ‘LINUX’ column, and Mac is on the left. Note that there is only a 64-bit version for Mac.
For Windows, there is a standard installer. For Mac, there is a standard ‘drag to the Applications folder’ style installer. On Linux, you can unpack the download to a location of your choice by issuing the command
tar -zvxf mongochef-linux-x64-dist.tar.gz
tar -zvxf mongochef-linux-x86-dist.tar.gz if you downloaded the 32-bit version) and then run the
launch script from within the unpacked directory.
Install the MongoDB Client Tools
MongoDB provides a number of command line tools for client machines. MongoChef’s IntelliShell requires one of these, the
mongo shell executable, to be accessible on your machine. To install these, go to https://www.mongodb.org/downloads.
You may need to scroll down a bit on that page to get to the downloads section. Here, you can download the distribution for your platform and ‘bitness’. There’s no separate distribution for just the client tools, the downloads on this page are what you need. In the Windows installer, there is an option to install just the client tools.
mongo shell is typically backward compatible with MongoDB database deployments of previous versions. For example, if you have to work with say a legacy MongoDB 2.4 system, a current 2.6 system and a new 3.0 system, you do not need to install the distribution for all those different versions. Simply install the latest version of the distribution (3.0 in our example), and you’ll be able to use it with all of the different versions of MongoDB deployments you need to work with.
Also note that if you are going to work with a MongoDB deployment that requires SSL encryption to connect to it, be sure to download a distribution that supports SSL encryption. As of this writing, the latest (3.0.3) versions of the Windows and Linux distributions do (though on Linux, you must also have the OpenSSL libraries installed). On Mac, the Homebrew package manager provides options to install an SSL-enabled version of the
mongodb package. You can also enable SSL support by building the tools from source, which is actually not as scary as it sounds.
The Windows MongoDB distribution is a standard Windows installer, the Mac and Linux distributions must be unpacked to a location of your choice using the command
tar -zvxf mongodb-<...>.tgz
mongodb-<...>.tgz refers to the name of the file you downloaded. (On Mac, you can also just double click the file to unpack it.)
OK, that’s us got everything we need installed, so let’s start MongoChef.
We need to configure MongoChef so that it knows where to find the
mongo shell executable we just installed.
First of all, we click on the ‘Preferences…’ menu (located in the application menu on Mac and in the ‘Edit’ menu on Windows and Linux) and then on the ‘IntelliShell’ tab. If you have previously had MongoDB installed on your system and the
mongo shell is available on your PATH, it will be shown in the first option here.
However, in this post we are going to select the particular version we just installed. To do this, select the second option and locate the
mongo shell executable. On Mac and Linux, this will be a binary file simply called
mongo located in the ‘bin’ directory where you unpacked the distribution. On Windows, it is a binary file called
mongo.exe and is located in the ‘bin’ directory of the MongoDB install location in ‘Program Files’. It will be a path similar to ‘
Now that that is configured, click OK, and we can start using IntelliShell!
An IntelliShell instance can be opened on the connection, database or collection level by selecting the particular connection, database or collection and then clicking the IntelliShell toolbar button, right-clicking it and selecting ‘Open IntelliShell…’ or using the keyboard shortcut ‘
Ctrl+L‘ / ‘⌘L’. (Note that if you do open at the connection level, you’ll be connected to the ‘test’ database as per the MongoDB default. So if your queries suddenly start returning no results – check you’re actually using the database you think you are!)
We can now begin using the amazing MongoChef IntelliShell – the richest MongoDB editing experience of any MongoDB GUI. Note there’s auto-completion not only of collection names and shell methods, but also of document key names, operators and further completions on return values, just the way you want it.
Special Note for Secondary Replica Set Members
Note that if you are connected to a replica set and want to run IntelliShell on a secondary member (for example, the replica set connection has a read preference of
secondaryPreferred), you will first need to run
rs.slaveOk() to be able to query freely. This is because, by default, MongoDB does not permit read operations from non-master (that is, slave or secondary) instances.
In MongoDB, reads to a primary have strict consistency, meaning that the data it provides reflects the latest writes at all times. This is more familiar and easier to work with when coming from other database systems.
Reads to secondaries in MongoDB however, have eventual consistency, meaning that changes to the system can propagate gradually and readable members are not required to reflect the latest writes at all times. This is less common and may surprise some users coming from other database systems.
rs.slaveOk() you are indicating to the system that you acknowledge that reads will be eventually consistent and wish to be able to query the secondary anyway. Following the principle of self-documenting code,
rs.slaveOk() should really be called
rs.iUnderstandThatHereReadsAreEventuallyConsistent AndIAmHappyToLiveWithTheConsequences SoPleaseLetMeQueryFreely(), but unless you have the amazing IntelliShell code completion available to you, that would be a little straining on the fingers.
OK, that’s it for this post. I hope you’re now successfully up and running with MongoChef’s IntelliShell. We’re always very keen to hear about your experiences and ideas for MongoChef. If you’d like to tell us about them please visit our feedback page or click the ‘Feedback’ toolbar button in the app.