Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

109 lines (105 sloc) 5.551 kb
doctype html
html(lang='en')
head
meta(charset="utf-8")
meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
title Mongoose Quick Start v#{package.version}
link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
style.
body.api
a#forkbanner(href="http://github.com/learnboost/mongoose")
img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
#links
#header
h1
a(href="../index.html")
.mongoose Mongoose
include includes/nav
#content
.module
h2 Getting Started
:markdown
_First be sure you have [MongoDB](http://www.mongodb.org/downloads) and [Node.js](http://nodejs.org/) installed._
Next install Mongoose from the command line using `npm`:
$ npm install mongoose
:markdown
Now say we like fuzzy kittens and want to record every kitten we ever meet in MongoDB.
The first thing we need to do is include mongoose in our project and open a connection to the `test` database on our locally running instance of MongoDB.
:js
// getting-started.js
var mongoose = require('mongoose');
mongoose.connect('mongodb://localhost/test');
:markdown
We have a pending connection to the test database running on localhost. We now need to get notified if we connect successfully or if a connection error occurs:
:js
var db = mongoose.connection;
db.on('error', console.error.bind(console, 'connection error:'));
db.once('open', function callback () {
// yay!
});
:markdown
Once our connection opens, our callback will be called. For brevity, let's assume that all following code is within this callback.
:markdown
With Mongoose, everything is derived from a [Schema](/docs/guide.html). Let's get a reference to it and define our kittens.
:js
var kittySchema = mongoose.Schema({
name: String
})
:markdown
So far so good. We've got a schema with one property, `name`, which will be a `String`. The next step is compiling our schema into a [Model](/docs/models.html).
:js
var Kitten = mongoose.model('Kitten', kittySchema)
:markdown
A model is a class with which we construct documents.
In this case, each document will be a kitten with properties and behaviors as declared in our schema.
Let's create a kitten document representing the little guy we just met on the sidewalk outside:
:js
var silence = new Kitten({ name: 'Silence' })
console.log(silence.name) // 'Silence'
:markdown
Kittens can meow, so let's take a look at how to add "speak" functionality to our documents:
:js
// NOTE: methods must be added to the schema before compiling it with mongoose.model()
kittySchema.methods.speak = function () {
var greeting = this.name
? "Meow name is " + this.name
: "I don't have a name"
console.log(greeting);
}
var Kitten = mongoose.model('Kitten', kittySchema)
:markdown
Functions added to the `methods` property of a schema get compiled into the `Model` prototype and exposed on each document instance:
:js
var fluffy = new Kitten({ name: 'fluffy' });
fluffy.speak() // "Meow name is fluffy"
:markdown
We have talking kittens! But we still haven't saved anything to MongoDB.
Each document can be saved to the database by calling its [save](/docs/api.html#model_Model-save) method. The first argument to the callback will be an error if any occured.
:js
fluffy.save(function (err, fluffy) {
if (err) // TODO handle the error
fluffy.speak();
});
:markdown
Say time goes by and we want to display all the kittens we've seen.
We can access all of the kitten documents through our Kitten [model](/docs/models.html).
:js
Kitten.find(function (err, kittens) {
if (err) // TODO handle err
console.log(kittens)
})
:markdown
We just logged all of the kittens in our db to the console.
If we want to filter our kittens by name, Mongoose supports MongoDBs rich [querying](/docs/queries.html) syntax.
:js
Kitten.find({ name: /^Fluff/ }, callback)
:markdown
This performs a search for all documents with a name property that begins with "Fluff" and returns the results to the callback.
h3 Congratulations
:markdown
That's the end of our quick start. We created a schema, added a custom document method, saved and queried kittens in MongoDB using Mongoose. Head over to the [guide](guide.html), or [API docs](api.html) for more.
script.
document.body.className = 'load';
include includes/googleanalytics
Jump to Line
Something went wrong with that request. Please try again.