Built-in Promises

    Mongoose async operations, like .save() and queries, return Promises/A+ conformant promises. This means that you can do things like MyModel.findOne({}).then() and yield MyModel.findOne({}).exec() (if you’re using co).

    For backwards compatibility, Mongoose 4 returns mpromise promises by default.

    2.     var gnr = new Band({
    3.       name: "Guns N' Roses",
    4.       members: ['Axl', 'Slash']
    5.     });
    7.     var promise = gnr.save();
    8.     assert.ok(promise instanceof require('mpromise'));
    10.     promise.then(function (doc) {
    11.       assert.equal(doc.name, "Guns N' Roses");
    12.     });

    Queries are not promises

    Mongoose queries are not promises. However, they do have a .then() function for yield and async/await. If you need a fully-fledged promise, use the .exec() function.

    2.     var query = Band.findOne({name: "Guns N' Roses"});
    3.     assert.ok(!(query instanceof require('mpromise')));
    5.     // A query is not a fully-fledged promise, but it does have a `.then()`.
    6.     query.then(function (doc) {
    7.       // use doc
    8.     });
    10.     // `.exec()` gives you a fully-fledged promise
    11.     var promise = query.exec();
    12.     assert.ok(promise instanceof require('mpromise'));
    14.     promise.then(function (doc) {
    15.       // use doc
    16.     });

    Plugging in your own Promises Library

    New in Mongoose 4.1.0

    While mpromise is sufficient for basic use cases, advanced users may want to plug in their favorite ES6-style promises library like bluebird, or just use native ES6 promises. Just set mongoose.Promise to your favorite ES6-style promise constructor and mongoose will use it.

    Mongoose tests with ES6 native promises, bluebird, and q. Any promise library that exports an ES6-style promise constructor should work in theory, but theory often differs from practice. If you find a bug, open an issue on GitHub

    2.     var query = Band.findOne({name: "Guns N' Roses"});
    4.     // Use native promises
    5.     mongoose.Promise = global.Promise;
    6.     assert.equal(query.exec().constructor, global.Promise);
    8.     // Use bluebird
    9.     mongoose.Promise = require('bluebird');
    10.     assert.equal(query.exec().constructor, require('bluebird'));
    12.     // Use q. Note that you **must** use `require('q').Promise`.
    13.     mongoose.Promise = require('q').Promise;
    14.     assert.ok(query.exec() instanceof require('q').makePromise);

    Promises for the MongoDB Driver

    The mongoose.Promise property sets the promises mongoose uses. However, this does not affect the underlying MongoDB driver. If you use the underlying driver, for instance Model.collection.db.insert(), you need to do a little extra work to change the underlying promises library. Note that the below code assumes mongoose >= 4.4.4.

    2.     var uri = 'mongodb://localhost:27017/mongoose_test';
    3.     // Use bluebird
    4.     var options = { promiseLibrary: require('bluebird') };
    5.     var db = mongoose.createConnection(uri, options);
    7.     Band = db.model('band-promises', { name: String });
    9.     db.on('open', function() {
    10.       assert.equal(Band.collection.findOne().constructor, require('bluebird'));
    11.     });