Accessing MongoDB from the Shell Client
Once you have installed, configured, and started MongoDB, you can access it through the MongoDB shell. The MongoDB shell is an interactive shell provided with MongoDB that allows you to access, configure, and administer MongoDB databases, users, and much more. You use the shell for everything from setting up user accounts to creating databases to querying the contents of the database.
The following sections take you through some of the most common administration tasks that you will be performing in the MongoDB shell. Here you will learn how to create user accounts, databases, and collections so that you will be able to follow the examples in the rest of the book. Also, you should be able to perform at least rudimentary queries on documents to better troubleshoot any problems with accessing data.
To start the MongoDB shell, execute the mongo command at the console prompt, and the shell should start up as shown in Figure 12.1.
Once you have accessed the MongoDB shell, you will be able to administer all aspects of MongoDB. Keep in mind that when you are using the MongoDB shell, it is based on JavaScript and therefore most JavaScript syntax is available. You should also remember that the shell provides direct access to the database and collections on the server so changes you make and tasks you perform in the shell directly impact the data and performance on the server.
Understanding MongoDB Shell Commands
The MongoDB shell provides several commands that you can execute from the shell prompt. You need to be familiar with these commands because you will be using them a lot:
help <option>: Displays syntax help for MongoDB shell commands. The option argument allows you to specify a specific area where you want help.
use <database>: Changes the current database handle. Database operations will be processed on the current database handle.
show <option>: Shows a list based on the option argument. The value of option can be:
dbs: Displays a list of databases.
collections: Displays a list of collections for the current database.
profile: Displays the most recent system.profile entries that take more than 1 millisecond.
log [name]: Displays the last segment of login memory. If nothing is specified for name, then global is used.
exit: Exits the database.
Understanding MongoDB Shell Methods
The MongoDB shell provides a number of methods for performing administrative functions. You can call these methods directly from the MongoDB shell or from a script that is executed in the MongoDB shell.
You will be using a large number of methods to perform various administrative functions. Some of these are covered in later sections and chapters in this book. For now, you need to be aware of the types of shell methods and how to access them. The following list provides a few examples of shell methods:
load(script): Loads and runs a JavaScript file inside the shell. Using it is a great way to script operations for the database.
UUID(string): Converts a 32-byte hex string into a BSON UUID.
db.auth(username, password): Authenticates you to the current database.
There are a lot of other shell methods. Many of them are covered in subsequent sections. For a full list of the native methods, check out http://docs.mongodb.org/manual/reference/method/#native.
Understanding Command Parameters and Results
The MongoDB shell is an interactive JavaScript shell that is tightly coupled with the MongoDB data structure. This means that much of the data interaction—from parameters passed to methods to data being returned from methods—is standard MongoDB documents, which are in most respects simply JavaScript objects. For example, when creating a user, you pass in a document similar to the following to define the user:
db.addUser( { user: "testUser",
userSource: "test",
roles: [ "read" ],
otherDBRoles: { testDB2: [ "readWrite" ] } } )
And when you’re listing the users for a database to the shell, the users are shown as a list of documents similar to this:
> db.system.users.find()
{ "_id" : ObjectId("529e71927c798d1dd56a63d9"), "user" : "dbadmin",
"pwd" : "78384f4d73368bd2d3a3e1da926dd269",
"roles": [ "readWriteAnyDatabase", "dbAdminAnyDatabase", "clusterAdmin" ] }
{ "_id" : ObjectId("52a098861db41f82f6e3d489"), "user" : "useradmin",
"pwd" : "0b4568ab22a52a6b494fd54e64fcee9f",
"roles" : [ "userAdminAnyDatabase" ] }
Scripting the MongoDB Shell
As you have seen, the commands, methods, and data structure of the MongoDB shell are based on interactive JavaScript. A great method of administering MongoDB is creating scripts that can be run multiple times or that can be ready to run at specific times, such as at upgrade.
A script file can contain any number of MongoDB commands, using JavaScript code such as conditional statements and loops. There are two ways to run a MongoDB shell script. The first is from the command line, using --eval. The --eval parameter accepts a JavaScript string or a JavaScript file and launches the MongoDB shell and immediately executes the JavaScript.
For example, the following command starts the MongoDB shell and executes db.getCollections() on the test database. Then it outputs the JSON string results as shown in Figure 12.2:
mongo test --eval "printjson(db.getCollectionNames())"
Note
If are using authentication, which you should, the script may need to authenticate to perform the commands.
You can also run a MongoDB shell script by using the load(script_path) method. This method loads a JavaScript file and immediately executes it. For example, the following shell command loads and executes the db_update.js script file:
load("/tmp/db_update.js")