Mongo-dart - MongoDB driver for Dart programming language

Server-side driver library for MongoDb implemented in pure Dart. Server side means all packages using dart:io, dart:html are not accepted.

NOTE Starting from release 6.0 of MongDb the old messages structure has been removed (almost completely). This means that some commands cannot be annymore executed. As per compatibility reasons with (very) old releases we are returning in some wrappers (like insert method) the result of this commands (in detail getLastError command), to let your programs work you should use instead the OP_MSG version. In general this methods are prefixed with modern, but this is not the case for all. For example, instead of insert, you should use insertOne, and instead of update you should use updateOne or updateMany.

Apis

Apis normally are created to behave in the most similar way to the mongo shell. Obviously not all and not necessarily in the same way, but at least the best possible way of performing a certain operation. Naming convention also, as far as possible, is maintained equal to the one of the shell. For compatibility with previous versions, apis for a certain method (for example find) normally foresee two versions:

• legacy (example legacyFind)
• modern (example modernFind)

So the method find acts as a wrapper for the two methods above. The difference is historical, "legacy" methods are intended to be used with MongoDb versions prior to 3.6, "modern" method for the more recent versions. The wrapper automatically will call the correct method, based on MongoDb version, but the interface normally resemble the "legacy" one, so, if you want to use the more recent features, you have to use the "modern" versions.

At present most of crud operations and commands have a "modern" version, but the porting is not yet complete.

Contribution

If you can contribute to the develpment of this package, your help is welcome!

Donate If you need a reliable driver like I do, please help me maintaining this software with a donation. This will allow me to dedicate more time on development, testing and documentation.

Basic usage

Obtaining connection

  var db = Db("mongodb://localhost:27017/mongo_dart-blog");
  await db.open();

or

  var db = await Db.create("mongodb+srv://<user>:<password>@<host>:<port>/<database-name>?<parameters>");
  await db.open();

Querying

find

Method find returns a stream of maps and accept query parameters, usually build by fluent API query builder provided by mongo_dart_query as top level getter where

  var coll = db.collection('find');
  // Fluent way
  await collection.find(where.eq('name', 'Tom').gt('rating', 10)).toList();
  // or Standard way
  await collection.find({'name': 'Tom', 'rating': {r'$gt': 10}}).toList();

Example for fluent .... - Example for standard ....

  await coll
      .find(where.gt("my_field", 995).sortBy('my_field'))
      .forEach((v) => print(v));

  //....

  await coll.find(where.sortBy('itemId').skip(300).limit(25)).toList();

Take notice in these samples that unlike mongo shell such parameters as projection (fields), limit and skip are passed as part of regular query through query builder. If you want to pass them separately, you have to use the modernFind method.

findOne

Method findOne take the same parameter and returns Future of just one map (mongo document) or null if not found

  val = await coll.findOne(where.eq("my_field", 17).fields(['str_field','my_field']));

Example....

Take notice in these samples that unlike mongo shell such parameters as projection (fields) and skip are passed as part of regular query through query builder. If you want to pass them separately, you have to use the modernFindOne method.

Inserting documents

insertMany

Use insertMany to insert some documents if you have mongoDb ver 3.6 or greater

  await usersCollection.insertMany([
    {'login': 'jdoe', 'name': 'John Doe', 'email': 'john@doe.com'},
    {'login': 'lsmith', 'name': 'Lucy Smith', 'email': 'lucy@smith.com'}
  ]);

(Example....)

or insertAll otherwise

  await usersCollection.insertAll([
    {'login': 'jdoe', 'name': 'John Doe', 'email': 'john@doe.com'},
    {'login': 'lsmith', 'name': 'Lucy Smith', 'email': 'lucy@smith.com'}
  ]);

insertOne

Use insertOne to insert only one documents if you have mongoDb ver 3.6 or greater

  await usersCollection.insertOne({'login': 'jdoe', 'name': 'John Doe', 'email': 'john@doe.com'});

(Example....)

or insert otherwise

  await usersCollection.insert({'login': 'jdoe', 'name': 'John Doe', 'email': 'john@doe.com'});

Updating documents

replaceOne

You can update the whole document with method replaceOne if you have mongoDb ver 3.6 or greater

  var v1 = await coll.findOne({"name": "c"});
  v1["value"] = 31;
  await coll.replaceOne({"name": "c"}, v1);

(Example....)

or save otherwise

  var v1 = await coll.findOne({"name": "c"});
  v1["value"] = 31;
  await coll.save(v1);

updateOne

You can perform field level updates on one document only with method updateOne and top level getter modify for ModifierBuilder fluent API (mongoDb ver 3.6 or greater).

  coll.updateOne(where.eq('name', 'Daniel Robinson'), modify.set('age', 31));

(Example....)

or update with MongoDb versions prior to 3.6

  coll.update(where.eq('name', 'Daniel Robinson'), modify.set('age', 31));

updateMany

You can perform field level updates on multiple documents only with method updateMany and top level getter modify for ModifierBuilder fluent API (mongoDb ver 3.6 or greater).

  coll.updateMany(where.eq('name', 'Daniel Robinson'), modify.set('age', 31));

(Example....)

or update and multiUpdate parameter with MongoDb versions prior to 3.6

  coll.update(where.eq('name', 'Daniel Robinson'), modify.set('age', 31), multiUpdate: true);

Removing documents

deleteOne

You can delete one document only with method deleteOne if you have mongoDb ver 3.6 or greater

  await coll.deleteOne({"name": "Karl"});

(Example....)

no specific method otherwise. You could use remove using a filter that selected only one document (best on "_id" field)

  await coll.remove({'_id': 25});

deleteMany

You can delete many documents in one time with method deleteMany if you have mongoDb ver 3.6 or greater

  await coll.deleteMany({"name": "Karl"});

(Example....)

or remove with MongoDb versions prior to 3.6

  students.remove(where.eq('name, 'Karl));

Simple app

Simple app based on JSON ZIPS dataset

Building aggregation queries

import 'package: mongo_dart/mongo_dart.dart';

main() async {
  final db = Db('mongodb://127.0.0.1/testdb');
  final pipeline = AggregationPipelineBuilder()
    .addStage(
      Match(where.eq('status', 'A').map['\$query']))
    .addStage(
      Group(
        id: Field('cust_id'),
        fields: {
          'total': Sum(Field('amount'))
        }
      )).build();
  final result =
    await DbCollection(db, 'orders')
      .aggregateToStream(pipeline).toList();
  result.forEach(print);
}

Secure connection

You can connect using a secured tls/ssl connection in one of these two ways:

• setting the secure connection parameter to true in db.open()

    await db.open(secure: true);

• adding a query parameter => "tls=true" (or "ssl=true").

    var db = DB('mongodb://www.example.com:27017/test?tls=true&authSource=admin');
              or
    var db = DB('mongodb://www.example.com:27017/test?ssl=true&authSource=admin');

When you use the mongodb+srv url schema, the "tls" (or "ssl") parameter is implicitly considered true.

You can also use certificates for tls handshake see this tutorial for more info.

Authentication

The driver supports three authentication methods:

• SCRAM_SHA_1
• SCRAM_SHA_256
• X509. See here for more details.

Atlas (MongoDb cloud service) connection

Atlas requires a tls connection, so now it is possible to connect to this cloud service. When creating a cluster Atlas shows you three ways of connecting: Mongo shell, Driver and MongoDb Compass Application. The connection string is in Seedlist Connection Format (starts with mongodb+srv://).

Take the Url related to the Driver mode and pass it to Db.create().

Please, not that Db.create is an asynchronous constructor, so you have to await for it.

  var db = await Db.create("mongodb+srv://<user>:<password>@<host>:<port>/<database>?<parameters>");
  await db.open();

OP_MSG

Only for those using mongodb version 3.6 or later

Starting from 3.6, a new protocol has been developed form mongodb to exchange data with the server. We are updating all commands and operation so that we can use the new protocol. This will be done gradually. At present we have developed the following operations:

There is the new collection helper method bulkWrite. The syntax is quite similar to that of the shell: collection.bulkWrite([{'insertOne': {'document': { "_id" : 1, "char" : "Brisbane", "class" : "monk", "lvl" : 4 }}}]); Like the one in the shell you can define the insertOne, deleteOne, deleteMany, updateOne, updateMany and replaceOne. In addition to the shell operation, you can use also an insertMany operation, with the following syntax: collection.bulkWrite([{'insertMany': {'documents': [{ "_id" : 1, "char" : "Brisbane", "class" : "monk", "lvl" : 4 }]}}]); Unlike the insertMany helper, this bulk operation does not suffer of the max number of documents per message limitation. You can also use directly the Bulk Object, if you prefer. Some examples: ordered Collection helper, unordered collection helper, ordered Bulk class and unordered Bulk Class

Aside to these changes we have also to mention the new Decimal128 type management (that is backed by the Rational class). This is inherited from enhancements in the BSON package

Last but not least, some commands:

See also

• API Doc

• Status

• Recent change notes

• Additional examples and tests