Mongoose
is a JavaScript framework that is commonly used in a Node.js application with a
MongoDB database. In this article, I am going to introduce you to Mongoose and
MongoDB, and more importantly where these technologies fit in to your
application.
What Is
MongoDB?
Let’s
start with MongoDB. MongoDB is a database that stores your data as documents.
Most commonly these documents resemble a JSON-like structure:
{ firstName: "Jamie", lastName: "Munro" }
A
document then is placed within a collection. As an example, the above document
example defines a user
object. This user
object then would typically be part
of a collection called users
.
One of
the key factors with MongoDB is its flexibility when it comes to structure.
Even though in the first example, the user
object contained a firstName
and
lastName
property, these properties are not required in every user
document that
is part of the users
collection. This is what makes MongoDB very different from
a SQL database like MySQL or Microsoft SQL Server that requires a strongly-defined database schema of each object it stores.
The
ability to create dynamic objects that are stored as documents in the database is
where Mongoose comes into play.
What Is
Mongoose?
Mongoose
is an Object Document Mapper (ODM). This means that Mongoose allows you to
define objects with a strongly-typed schema that is mapped to a MongoDB
document.
Mongoose
provides an incredible amount of functionality around creating and working with
schemas. Mongoose currently contains eight SchemaTypes that a property is saved as
when it is persisted to MongoDB. They are:
- String
- Number
- Date
- Buffer
- Boolean
- Mixed
- ObjectId
- Array
Each data
type allows you to specify:
- a default value
- a custom validation function
- indicate a field is required
- a get function that allows
you to manipulate the data before it is returned as an object - a set function that allows
you to manipulate the data before it is saved to the database - create indexes to allow data to be fetched faster
Further
to these common options, certain data types allow you to further customize how
the data is stored and retrieved from the database. For example, a String
data
type also allows you to specify the following additional options:
- convert it to lowercase
- convert it to uppercase
- trim data prior to saving
- a regular expression that can
limit data allowed to be saved during the validation process - an enum that can define a
list of strings that are valid
The
Number
and Date
properties both support specifying a minimum and maximum value
that is allowed for that field.
Most of
the eight allowed data types should be quite familiar to you. However, there are
several exceptions that may jump out to you, such as Buffer
, Mixed
, ObjectId
,
and Array
.
The
Buffer
data type allows you to save binary data. A common example of binary
data would be an image or an encoded file, such as a PDF document.
The Mixed
data type turns the property into an “anything goes” field. This
field resembles how many developers may use MongoDB because there is no defined
structure. Be wary of using this data type as it loses many of the great features
that Mongoose provides, such as data validation and detecting entity changes
to automatically know to update the property when saving.
The
ObjectId
data type commonly specifies a link to another document in your
database. For example, if you had a collection of books and authors, the book
document might contain an ObjectId
property that refers to the specific author of the document.
The Array
data type allows you to store JavaScript-like arrays. With an Array data type,
you can perform common JavaScript array operations on them, such as push, pop,
shift, slice, etc.
Quick
Recap
Before
moving on and generating some code, I just wanted to recap what we just
learned. MongoDB is a database that allows you to store documents with a
dynamic structure. These documents are saved inside a collection.
Mongoose
is a JavaScript library that allows you to define schemas with strongly typed
data. Once a schema is defined, Mongoose lets you create a Model based on a
specific schema. A Mongoose Model is then mapped to a MongoDB Document via the
Model’s schema definition.
Once you
have defined your schemas and models, Mongoose contains many different
functions that allow you to validate, save, delete, and query your data using
common MongoDB functions. I’ll talk about this more with the concrete code
examples to follow.
Installing
MongoDB
Before we
can begin creating our Mongoose schemas and models, MongoDB must be installed
and configured. I would suggest visiting MongoDB’s
Download page. There are several different options available to install. I
have linked to the Community Server. This allows you to install a version
specific to your operating system. MongoDB also offers an Enterprise Server and
a cloud support installation. Since entire books could be written on installing,
tuning, and monitoring MongoDB, I am going to stick with the Community Server.
Once
you’ve downloaded and installed MongoDB for your operating system of choice,
you will need to start the database. Rather than reinventing the wheel, I
would suggest visiting MongoDB’s documentation on how to install
the MongoDB Community Edition.
I’ll wait
here while you configure MongoDB. When you’re ready, we can move on to setting
up Mongoose to connect to your newly installed MongoDB database.
Setting
Up Mongoose
Mongoose
is a JavaScript framework, and I am going to use it in a Node.js
application. If you already have Node.js installed, you can move on to the next
step. If you do not have Node.js installed, I suggest you begin by visiting the
Node.js Download page and
selecting the installer for your operating system.
With
Node.js set up and ready to go, I am going to create a new application and then
install the Mongoose NPM Package.
With a
command prompt that is set to where you wish your application to be installed,
you can run the following commands:
mkdir mongoose_basics cd mongoose_basics npm init
For the
initialization of my application, I left everything as their default values.
Now I’m going to install the mongoose package as follows:
npm install mongoose --save
With all
the prerequisites configured, let’s connect to a MongoDB database. I’ve placed
the following code inside an index.js file because I chose that as the starting
point for my application:
var mongoose = require('mongoose'); mongoose.connect('mongodb://localhost/mongoose_basics');
The first
line of code includes the mongoose
library. Next, I open a connection to a
database that I’ve called mongoose_basics
using the connect
function.
The
connect
function accepts two other optional parameters. The second parameter is
an object of options where you can define things like the username and
password, if required. The third parameter, which can also be the second
parameter if you have no options, is the callback function after attempting to connect. The callback
function can be used in one of two ways:
mongoose.connect(uri, options, function(error) { // Check error in initial connection. There is no 2nd param to the callback. }); // Or using promises mongoose.connect(uri, options).then( () => { /** ready to use. The `mongoose.connect()` promise resolves to undefined. */ }, err => { /** handle initial connection error */ } );
To avoid
a potential introduction to JavaScript Promises, I will use the first way.
Below is an updated index.js file:
var mongoose = require('mongoose'); mongoose.connect('mongodb://localhost/mongoose_basics', function (err) { if (err) throw err; console.log('Successfully connected'); });
If an
error occurs when connecting to the database, the exception is thrown and all
further processing is stopped. When no error occurs, I have logged a success
message to the console.
Mongoose is now set up and connected to a database
called mongoose_basics
. My MongoDB connection is using no username, password,
or custom port. If you need to set these options or any other option
during connection, I suggest reviewing the Mongoose Documentation on
connecting. The documentation provides detailed explanations of the many
options available as well as how to create multiple connections, connection pooling,
replicas, etc.
With a
successful connection, let’s move on to define a Mongoose Schema.
Defining
a Mongoose Schema
During the introduction, I showed a user
object that contained two properties: firstName
and lastName
. In the following example, I’ve translated that document into a Mongoose Schema:
var userSchema = mongoose.Schema({ firstName: String, lastName: String });
This is a very basic Schema that just contains two properties with no attributes associated with it. Let’s expand upon this example by converting the first and last name properties to be child objects of a name
property. The name
property will comprise both the first and last name. I’ll also add a created
property that is of type Date
.
var userSchema = mongoose.Schema({ name: { firstName: String, lastName: String }, created: Date });
As you can see, Mongoose allows me to create very flexible schemas with many different possible combinations of how I am able to organize my data.
In this next example, I am going to create two new schemas that will demonstrate how to create a relationship to another schema: author
and book
. The book
schema will contain a reference to the author
schema.
var authorSchema = mongoose.Schema({ _id: mongoose.Schema.Types.ObjectId, name: { firstName: String, lastName: String }, biography: String, twitter: String, facebook: String, linkedin: String, profilePicture: Buffer, created: { type: Date, default: Date.now } });
Above is the author
schema that expands upon the concepts of the user
schema that I created in the previous example. To link the Author and Book together, the first property of the author
schema is an _id
property that is an ObjectId
schema type. _id
is the common syntax for creating a primary key in Mongoose and MongoDB. Then, like the user
schema, I’ve defined a name
property containing the author’s first and last name.
Expanding upon the user
schema, the author
contains several other String
schema types. I’ve also added a Buffer
schema type that could hold the author’s profile picture. The final property holds the created date of the author; however, you may notice it is created slightly differently because it has defined a default value of “now”. When an author is persisted to the database, this property will be set to the current date/time.
To complete the schema examples, let’s create a book
schema that contains a reference to the author by using the ObjectId
schema type:
var bookSchema = mongoose.Schema({ _id: mongoose.Schema.Types.ObjectId, title: String, summary: String, isbn: String, thumbnail: Buffer, author: { type: mongoose.Schema.Types.ObjectId, ref: 'Author' }, ratings: [ { summary: String, detail: String, numberOfStars: Number, created: { type: Date, default: Date.now } } ], created: { type: Date, default: Date.now } });
The book
schema contains several properties of type String
. As mentioned above, it contains a reference to the author
schema. To further demonstrate the powerful schema definitions, the book
schema also contains an Array
of ratings
. Each rating consists of a summary
, detail
, numberOfStars
, and created
date property.
Mongoose allows you the flexibility to create schemas with references to other schemas or, as in the above example with the ratings
property, it allows you to create an Array
of child properties that could be contained in a related schema (like book to author) or inline as in the above example (with book to a ratings Array
).
Creating and Saving Mongoose Models
Since the author
and book
schemas demonstrate Mongoose’s schema flexibility, I am going to continue using those schemas and derive an Author
and Book
model from them.
var Author = mongoose.model('Author', authorSchema); var Book = mongoose.model('Book', bookSchema);
A Mongoose Model, when saved, creates a Document in MongoDB with the properties as defined by the schema it is derived from.
To demonstrate creating and saving an object, in this next example, I am going to create several objects: an Author
Model and several Book
Models. Once created, these objects will be persisted to MongoDB using the save
method of the Model.
var jamieAuthor = new Author { _id: new mongoose.Types.ObjectId(), name: { firstName: 'Jamie', lastName: 'Munro' }, biography: 'Jamie is the author of ASP.NET MVC 5 with Bootstrap and Knockout.js.', twitter: 'https://twitter.com/endyourif', facebook: 'https://www.facebook.com/End-Your-If-194251957252562/' }; jamieAuthor.save(function(err) { if (err) throw err; console.log('Author successfully saved.'); var mvcBook = new Book { _id: new mongoose.Types.ObjectId(), title: 'ASP.NET MVC 5 with Bootstrap and Knockout.js', author: jamieAuthor._id, ratings:[{ summary: 'Great read' }] }; mvcBook.save(function(err) { if (err) throw err; console.log('Book successfully saved.'); }); var knockoutBook = new Book { _id: new mongoose.Types.ObjectId(), title: 'Knockout.js: Building Dynamic Client-Side Web Applications', author: jamieAuthor._id }; knockoutBook.save(function(err) { if (err) throw err; console.log('Book successfully saved.'); }); });
In the above example, I’ve shamelessly plugged a reference to my two most recent books. The example starts by creating and saving a jamieObject
that is created from anAuthor
Model. Inside the save
function of the jamieObject
, if an error occurs, the application will output an exception. When the save is successful, inside the save
function, the two book objects are created and saved. Similar to the jamieObject
, if an error occurs when saving, an error is outputted; otherwise, a success message is outputted in the console.
To create the reference to the Author, the book objects both reference the author
schema’s _id
primary key in the author
property of the book
schema.
Validating Data Before Saving
It’s quite common for the data that will end up creating a model to be populated by a form on a webpage. Because of this, it’s a good idea to validate this data prior to saving the Model to MongoDB.
In this next example, I’ve updated the previous author schema to add validation on the following properties: firstName
, twitter
, facebook
, and linkedin
.
var authorSchema = mongoose.Schema({ _id: mongoose.Schema.Types.ObjectId, name: { firstName: { type: String, required: true }, lastName: String }, biography: String, twitter: { type: String, validate: { validator: function(text) { return text.indexOf('https://twitter.com/') === 0; }, message: 'Twitter handle must start with https://twitter.com/' } }, facebook: { type: String, validate: { validator: function(text) { return text.indexOf('https://www.facebook.com/') === 0; }, message: 'Facebook must start with https://www.facebook.com/' } }, linkedin: { type: String, validate: { validator: function(text) { return text.indexOf('https://www.linkedin.com/') === 0; }, message: 'LinkedIn must start with https://www.linkedin.com/' } }, profilePicture: Buffer, created: { type: Date, default: Date.now } });
The firstName
property has been attributed with the required
property. Now when I call the save
function, Mongoose will return an error with a message indicating the firstName
property is required. I chose not to make the lastName
property required in case Cher or Madonna were to be authors in my database.
The twitter
, facebook
, and linkedin
properties all have very similar custom validators applied to them. They each ensure that the values begin with the social networks’ respective domain name. These fields are not required, so the validator will only be applied when data is supplied for that property.
Searching for and Updating Data
An introduction to Mongoose wouldn’t be complete without an example of searching for a record and updating one or more properties on that object.
Mongoose provides several different functions to find data for a specific Model. The functions are find
, findOne
, and findById
.
The find
and findOne
functions both accept an object as input allowing for complex searches, whereas findById
accepts just a single value with a callback function (an example will follow shortly). In this next example, I am going to demonstrate how to find all books that contain the string “mvc” in their title.
Book.find({ title: /mvc/i }).exec(function(err, books) { if (err) throw err; console.log(books); });
Inside the find
function, I am searching for the case insensitive string “mvc” on the title
property. This is accomplished using the same syntax for searching a string with JavaScript.
The find function call also be chained to other query methods, such as where
, and
, or
, limit
, sort
, any
, etc.
Let’s expand upon the previous example to limit our results to the first five books and sort on the created date descending. This will return up to the five most recent books containing “mvc” in the title.
Book.find({ title: /mvc/i }).sort('-created') .limit(5) .exec(function(err, books) { if (err) throw err; console.log(books); });
After applying the find
function, the order of the other functions is not important because all of the chained functions are compiled together into a single query and not executed until the exec
function is called.
As I mentioned earlier, the findById
is executed a bit differently. It executes immediately and accepts a callback function, instead of allowing for a chain of functions. In this next example, I am querying a specific author by their _id
.
Author.findById('59b31406beefa1082819e72f', function(err, author) { if (err) throw err; console.log(author); });
The _id
in your case might be slightly different. I copied this _id
from a previous console.log
when finding a list of books with “mvc” in their title.
Once an object has been returned, you can modify any of its properties to update it. Once you have made the necessary changes, you call the save
method, just like when you were creating the object. In this next example, I will extend the findbyId
example and update the linkedin
property on the author.
Author.findById('59b31406beefa1082819e72f', function(err, author) { if (err) throw err; author.linkedin = 'https://www.linkedin.com/in/jamie-munro-8064ba1a/'; author.save(function(err) { if (err) throw err; console.log('Author updated successfully'); }); });
After the author is successfully retrieved, the linkedin
property is set and the save
function is called. Mongoose is able to detect that the linkedin
property was changed, and it will send an update statement to MongoDB on only the properties that have been modified. If an error occurred when saving, an exception will be thrown and will halt the application. When successful, a success message is logged to the console.
Mongoose also offers two additional functions that make finding an object and saving it in a single step with the appropriately named functions: findByIdAndUpdate
and findOneAndUpdate
. Let’s update the previous example to use the findByIdAndUpdate
.
Author.findByIdAndUpdate('59b31406beefa1082819e72f', { linkedin: 'https://www.linkedin.com/in/jamie-munro-8064ba1a/' }, function(err, author) { if (err) throw err; console.log(author); });
In the previous example, the properties to update are supplied as an object to the second parameter of the findByIdAndUpdate
function. The callback function is now the third parameter. When the update is successful, the author
object returned contains the updated information. This is logged to the console to see the updated author’s properties.
Final Sample Code
Throughout this article, I provided small snippets of code identifying a very specific action, such as creating a schema, creating a model, etc. Let’s put it all together in a full example.
Firstly, I’ve created two additional files: author.js
and book.js
. These files contain their respective schema definitions and the model creation. The final line of code makes the model available for use in the index.js
file.
Let’s start with the author.js file:
var mongoose = require('mongoose'); var authorSchema = mongoose.Schema({ _id: mongoose.Schema.Types.ObjectId, name: { firstName: { type: String, required: true }, lastName: String }, biography: String, twitter: { type: String, validate: { validator: function(text) { return text.indexOf('https://twitter.com/') === 0; }, message: 'Twitter handle must start with https://twitter.com/' } }, facebook: { type: String, validate: { validator: function(text) { return text.indexOf('https://www.facebook.com/') === 0; }, message: 'Facebook must start with https://www.facebook.com/' } }, linkedin: { type: String, validate: { validator: function(text) { return text.indexOf('https://www.linkedin.com/') === 0; }, message: 'LinkedIn must start with https://www.linkedin.com/' } }, profilePicture: Buffer, created: { type: Date, default: Date.now } }); var Author = mongoose.model('Author', authorSchema); module.exports = Author;
Next comes the book.js
file:
var mongoose = require('mongoose'); var bookSchema = mongoose.Schema({ _id: mongoose.Schema.Types.ObjectId, title: String, summary: String, isbn: String, thumbnail: Buffer, author: { type: mongoose.Schema.Types.ObjectId, ref: 'Author' }, ratings: [ { summary: String, detail: String, numberOfStars: Number, created: { type: Date, default: Date.now } } ], created: { type: Date, default: Date.now } }); var Book = mongoose.model('Book', bookSchema); module.exports = Book;
And finally, the updated index.js
file:
var mongoose = require('mongoose'); var Author = require('./author'); var Book = require('./book'); mongoose.connect('mongodb://localhost/mongoose_basics', function (err) { if (err) throw err; console.log('Successfully connected'); var jamieAuthor = new Author({ _id: new mongoose.Types.ObjectId(), name: { firstName: 'Jamie', lastName: 'Munro' }, biography: 'Jamie is the author of ASP.NET MVC 5 with Bootstrap and Knockout.js.', twitter: 'https://twitter.com/endyourif', facebook: 'https://www.facebook.com/End-Your-If-194251957252562/' }); jamieAuthor.save(function(err) { if (err) throw err; console.log('Author successfully saved.'); var mvcBook = new Book({ _id: new mongoose.Types.ObjectId(), title: 'ASP.NET MVC 5 with Bootstrap and Knockout.js', author: jamieAuthor._id, ratings:[{ summary: 'Great read' }] }); mvcBook.save(function(err) { if (err) throw err; console.log('Book successfully saved.'); }); var knockoutBook = new Book({ _id: new mongoose.Types.ObjectId(), title: 'Knockout.js: Building Dynamic Client-Side Web Applications', author: jamieAuthor._id }); knockoutBook.save(function(err) { if (err) throw err; console.log('Book successfully saved.'); }); }); });
In the above example, all of the Mongoose actions are contained within the connect
function. The author
and book
files are included with the require
function after including the mongoose
library.
With MongoDB running, you can now run the complete Node.js application with the following command:
node index.js
After I saved some data to my database, I updated the index.js
file with the find functions as follows:
var mongoose = require('mongoose'); var Author = require('./author'); var Book = require('./book'); mongoose.connect('mongodb://localhost/mongoose_basics', function (err) { if (err) throw err; console.log('Successfully connected'); Book.find({ title: /mvc/i }).sort('-created') .limit(5) .exec(function(err, books) { if (err) throw err; console.log(books); }); Author.findById('59b31406beefa1082819e72f', function(err, author) { if (err) throw err; author.linkedin = 'https://www.linkedin.com/in/jamie-munro-8064ba1a/'; author.save(function(err) { if (err) throw err; console.log('Author updated successfully'); }); }); Author.findByIdAndUpdate('59b31406beefa1082819e72f', { linkedin: 'https://www.linkedin.com/in/jamie-munro-8064ba1a/' }, function(err, author) { if (err) throw err; console.log(author); }); });
Once again, you can run the application with the command: node index.js
.
Summary
After reading this article, you should be able to create extremely flexible Mongoose Schemas and Models, apply simple or complex validation, create and update documents, and finally search for the documents that were created.
Hopefully you now feel comfortable using Mongoose. If you are looking to learn more, I would suggest reviewing the Mongoose Guides which delve into more advanced topics such as population, middleware, promises, etc.
Happy hunting (poor Mongoose animal reference)!
Powered by WPeMatico