This chapter covers installing MongoDB and accessing the shell. The chapter focuses on some basic administrative tasks such as setting up user accounts and authentication. The chapter then wraps up by describing how to administer databases, collections, and documents.

The following sections cover installation, starting and stopping the database engine, and accessing the shell client. Once you can do those things you are ready to begin using MongoDB in your environment.

For the purposes of this book and learning MongoDB, the standard edition of MongoDB is perfect. Before continuing, go to the MongoDB website at http://docs.mongodb.org/manual/installation/. Follow the links and instructions to download and install MongoDB in your environment:

As part of the installation and setup process, perform the following steps:

1. Download and extract the MongoDB files.

2. Add the <mongo_install_location>/bin to your system path.

3. Create a data files directory: <mongo_data_location>/data/db.

4. Start MongoDB using the following command from the console prompt: mongod –dbpath <mongo_data_location>/data/db

The mongod executable accepts several different parameters that provide methods of controlling its behavior. For example, you can configure the IP address and port MongoDB listens on as well as logging and authentication. Table 12.1 provides a list of some of the most commonly used parameters.

Here is an example of starting MongoDB with a port and dbpath parameters:

mongod –port 28008 –dbpath <mongo_data_location>/data/db

Table 12.1 mongod command-line parameters

To stop the MongoDB database from the shell client, use the following commands to switch to the admin database and then shut down the database engine:

use admin
db.shutdownServer()

The following sections take you through some of the most common administration tasks that you perform in the MongoDB shell. Specifically, you need to be able to create user accounts, databases, and collections to follow the examples in the rest of the book. Also you should be able to perform at least rudimentary queries on documents to help you troubleshoot any problems with accessing data.

To start the MongoDB shell, first make sure that mongod is running, and then run the mongod command, then execute the mongo command from the console prompt. The shell should start up as shown in Figure 12.1.

Figure 12.1 Starting the MongoDB console shell

Once you have accessed the MongoDB shell, you can administer all aspects of MongoDB. There are a couple of things to keep in mind when using MongoDB. First is that it is based on JavaScript and most of its syntax is available. Second, the shell provides direct access to the database and collections on the server so changes you make directly impact the data on the server.

help <option>: Displays syntax help for MongoDB shell commands. The option argument allows you to specify an area where you want help.

use <database>: Changes the current database handle. Database operations are processed on the current database handle.

db.help: Displays help options for the database methods.

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 five most recent system.profile entries taking more than 1 millisecond.

databases: Displays a list of all available databases.

roles: Displays a list of all roles for the current database, both built-in and user-defined.

users: Displays a list of all users for that database.

exit: Exits the database.

There are many methods that you can use 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. This 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 different 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.

Click here to view code image

db.createUser( { user: "testUser",
              roles: [ "read" ],
              otherDBRoles: { testDB2: [ "readWrite" ] } } )

And when listing the users for a database to the shell, the users are shown as a list of documents similar to this:

Click here to view code image

> use admin
switched to db admin
> db.system.users.find()
{ "_id" : ObjectId("529e71927c798d1dd56a63d9"), "user" : "dbadmin", "pwd" :
"78384f4d73368bd2d3a3e1da926dd269", "roles"
: [  "readWriteAnyDatabase",  "dbAdminAnyDatabase",  "clusterAdmin" ] }
{ "_id" : ObjectId("52a098861db41f82f6e3d489"), "user" : "useradmin", "pwd" :
"0b4568ab22a52a6b494fd54e64fcee9f", "roles
" : [  "userAdminAnyDatabase" ] }

The script file can contain any number of MongoDB commands using JavaScript syntax such as conditional statements and loops. There are two methods to run a MongoDB shell script. The first is from the console command line using --eval. The --eval parameter accepts a JavaScript string or a JavaScript file, launches the MongoDB shell, and immediately executes the JavaScript.

For example, the following command starts the MongoDB shell, executes db.getCollections() on the test database, and outputs the JSON string results as shown in Figure 12.2:

mongo test --eval "printjson(db.getCollectionNames())"

Figure 12.2 Executing a JavaScript file from the MongoDB console shell command line

The second method is to execute a JavaScript from the MongoDB shell prompt 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")

use admin
show users

Figure 12.3 Listing users on the admin database

You can also use a query such as find on the db.system.users collection. The difference is that db.system.users.find() returns a cursor object that you can use to access the User documents. For example, the following code gets a cursor for users in the admin database and returns the count of users:

use admin
cur = db.system.users.find()
cur.count()

Table 12.2 Fields used when creating users with the db.createUser() method

MongoDB provides a number of different roles that can be assigned to a user account. These roles give you the ability to implement intricate privileges and restrictions on user accounts. Table 12.3 lists some of the more common roles that can be assigned to users.

Table 12.3 Database roles that can be assigned to user accounts

To create a user you should switch to that database and then use the createUser() method to create the user object. The following MongoDB shell command illustrates creating a basic administrator user to the test database:

use test
db.createUser( { user: "testUser",
    pwd: "test",
    roles: [ "readWrite", "dbAdmin" ] } )

Now here’s a more complex example. The following commands add the same user to the newDB database with only read rights and give them readWrite privileges to the testDB2 database:

use newDB
db.createUser( { user: "testUser",
    roles: [ "read" ],
    otherDBRoles: { testDB2: [ "readWrite" ] } } )

use testDB
db.removeUser("testUser")

Initially, the admin database does not have any users assigned to it. When no users are defined in the admin database, MongoDB allows connections on the local host to have full administrative access to the database. Therefore, your first step in setting up a new MongoDB instance is to create User Administrator and Database Administrator accounts. The User Administrator account provides the ability to create user accounts in the admin and other databases. You also need to create a Database Administrator account that you can use as a superuser to manage databases, clustering, replication, and other aspects of MongoDB.

Creating a User Administrator account is done by executing the following two commands in the MongoDB shell to access the admin database and then add a user with userAdminAnyDatabase rights.

use admin
db.createUser( { user: "<username>",
    pwd: "<password>",
    roles: [ "userAdminAnyDatabase" ] } )

The User Administrator account should be created with userAdminAnyDatabase as the only role. This gives the User Administrator the ability to create new user accounts but not to manipulate the database beyond that. For example, create a User Administrator account with the username useradmin and a password of test as shown in Figure 12.4:

use admin
db.createUser( { user: "useradmin",
    pwd: "test",
    roles: [ "userAdminAnyDatabase" ] } )

Figure 12.4 Creating the User Administrator account

mongod –dbpath <mongo_data_location>/data/db --auth

Clients will now have to use a username and password to access the database. Also, when you access MongoDB from the shell, you need to execute the following commands to authenticate to the admin database so that you can add users with rights to the database:

use admin
db.auth("useradmin", "test")

You can also authenticate to the admin database when starting the MongoDB shell using the --username and --password options, for example:

mongo --username "useradmin" --password "test"

use admin
db.createUser( { user: "dbadmin",
    pwd: "test",
    roles: [ "readWriteAnyDatabase", "dbAdminAnyDatabase", "clusterAdmin" ] } )

You can then use that user in the MongoDB shell to administer databases. Once you have created the new administrator account, you can authenticate as that user using the following commands:

use admin
db.auth("dbadmin", "test")

You can also authenticate to the admin database as the Database Administrator when starting the MongoDB shell using the --username and --password options, for example:

mongo --username "dbadmin" --password "test"

show dbs

To switch the current database, you can use the db.getSiblingDB(database) method or the use <database> method. For example, both of the following methods switch the current database handle to testDB. Either one is acceptable and sets the value of db to the database specified. You can then use db to manage the new current database:

db = db.getSiblingDB('testDB')
use testDB

use newDB
db.createCollection("newCollection")

To verify that the new database exists, you can then use show dbs as shown in Figure 12.5.

Figure 12.5 Creating a new database in the MongoDB console shell

To delete a database from the MongoDB shell, use the dropDatabase() method. For example, to delete the newDB database, use the following commands to change to the newDB database and then delete it:

use newDB
db.dropDatabase()

Be aware that dropDatabase() removes the current database, but it does not change the current database handle. That means that if you drop a database and then create a collection using the handle without changing the current database first, the dropped database is re-created.

Figure 12.6 shows an example of deleting the newDB from MongoDB:

Figure 12.6 Deleting a database in the MongoDB console shell

To create a copy of a database, you switch to that database and then use copyDatabase(origin, destination, [hostname]) to create a copy. The origin parameter is a string specifying the name of the database to copy. The destination parameter specifies the name of the database to create on this MongoDB server. The optional hostname parameter specifies a hostname of the origin database MongoDB server if you are copying a database from a different host. For example:

db.copyDatabase('customers', 'customers_archive')

use test
show collections

Table 12.4 Options that can be specified when creating collections

For example, the following lines of code create a new collection called newCollection in the testDB database as shown in Figure 12.7:

db.createCollection("newCollection")

Figure 12.7 Creating a new collection in the MongoDB console shell

To delete a collection in the MongoDB shell, you need to switch to the correct database, get the collection object, and then call the drop() function on that object. For example, the following code deletes the newCollection collection from the testDB database as shown in Figure 12.8:

use testDB
show collections
coll = db.getCollection("newCollection")
coll.drop()
show collections

Figure 12.8 Deleting a collection in the MongoDB console shell

The MongoDB shell provides full querying functionality to find documents in collections using the find(query) method on the collection object. The optional query parameter specifies a query document with fields and values to match documents against in the collection. The documents that match the query are removed from the collection. Using the find() method with no query parameter returns all documents in the collection.

For example, the following lines of code first query every item in the collection and then retrieve the documents whose speed field is equal to 120mph. The results are shown in Figure 12.9.

use testDB
coll = db.getCollection("newCollection")
coll.find()
coll.find({speed:"120mph"})

Figure 12.9 Finding documents in a collection

To add documents to a collection, you need to get the collection object and then call the insert(document) or save(document) method on that object. The document parameter is a well-formatted JavaScript object that is converted to BSON and stored in the collection. As an example, the following commands create three new objects inside a collection as shown in Figure 12.10:

Click here to view code image

use testDB
coll = db.getCollection("newCollection")
coll.find()
coll.insert({ vehicle: "plane", speed: "480mph" })
coll.insert({ vehicle: "car", speed: "120mph" })
coll.insert({ vehicle: "train", speed: "120mph" })
coll.find()

Figure 12.10 Creating documents in a collection

To remove documents from a collection, you need to get the collection object and then call the remove(query) method on that object. The optional query parameter specifies a query document with fields and values to match documents against in the collection. The documents that match the query are removed from the collection. Using the remove() method with no query parameter removes all documents in the collection. As an example, the following commands first remove documents where the vehicle is plane and then all documents from the collection, as shown in Figure 12.11:

use testDB
coll = db.getCollection("newCollection")
coll.find()
coll.remove({vehicle: "plane"})
coll.find()
coll.remove()
coll.find()

Figure 12.11 Deleting documents from a collection

To update documents in a collection, you need to get the collection. Then you can use a couple of different methods: The save(object) method saves changes that you have made to an object, and the update(query, update, options) method queries for documents in the collection and then updates them as they are found.

When using the update() method, the query parameter specifies a query document with fields and values to match documents against in the collection. The update parameter is an object that specifies the update operator to use when making the update. For example, $inc increments the value of the field, $set sets the value of the field, $push pushes an item onto an array, and so on. For example, the following update object increments one field, sets another, and then renames a third:

{ $inc: {count: 1}, $set: {name: "New Name"}, $rename: {"nickname": "alias"} }

The options parameter of update() is an object that has two properties—multi and upsert—that are both Boolean values. If upsert is true, a new document is created if none are found. If multi is true, all documents that match the query are updated; otherwise, only the first document is updated.

For example, the following commands update documents with a speed of 120mph by setting the speed to 150 and adding a new field called updated. Also the save() method is used to save changes to the plane document. The console output is shown in Figure 12.12:

Click here to view code image

use testDB
coll = db.getCollection("newCollection")
coll.find()
coll.update({ speed: "120mph" },
            { $set: { speed: "150mph" , updated: true } },
            { upsert: false, multi: true })
coll.save({ "_id" : ObjectId("52a0caf33120fa0d0e424ddb"),
            "vehicle" : "plane", "speed" : "500mph" })
coll.find()

Figure 12.12 Updating documents from a collection

This chapter discussed the process of installing MongoDB and accessing the MongoDB shell. You learned how to interact with the shell to create user accounts, databases, collections, and documents.