mongo_dart 0.7.0+1
mongo_dart: ^0.7.0+1 copied to clipboard
MongoDB driver, implemented in pure Dart. All CRUD operations, aggregation pipeline and more!
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 is nota accepted.
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!
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']));
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'}
]);
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'});
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(v1);
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));
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));
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"});
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"});
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.
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:
Command | Status | Legacy alternative | Notes |
---|---|---|---|
- | Not developed | Save |
This method has been deprecated. |
insertOne |
Tested | legacyInsert |
The old method insert is a wrapper that calls insertOne if you are running MongoDb 3.6 or later, otherwise legacyInsert . |
insertMany |
Tested | legacyInsertAll |
Allows to insert many documents in one command. It is subject to the max number of documents per message limit (at present <4.4> 100,000).The old method insertAll is a wrapper that calls insertMany if you are running MongoDb 3.6 or later, otherwise legacyInsertAll . |
deleteOne | Tested | - | Allows to delete one document. Example Example 2 |
deleteMany | Tested | legacyRemove |
The old method remove is a wrapper that calls deleteMany if you are running MongoDb 3.6 or later, otherwise legacyRemove . Allows to delete many documents in one commnand. Example |
updateOne | Tested | - | Allows to update one document Example |
updateMany | Tested | - | Allows to update many documents in one command. Example |
modernUpdate | Tested | legacyUpdate |
The old method update now is only a wrapper. If you are running MongoDb 3.6 or later, modernUpdate is called, otherwise legacyUpdate |
- | To be developed yet | count |
|
modernDistinct |
Experimental | legacyDistinct |
The old method distinct now is only a wrapper. If you are running MongoDb 3.6 or later, modernDistinct is called, otherwise legacyDistinct |
modernFind |
Tested | legacyFind |
The old method find now is simply a wrapper. If you are running MongoDb 3.6 or later, modernFind is called, otherwise legacyFind |
modernFindOne |
Tested | legacyFindOne |
The old method findOne now is simply a wrapper. If you are running MongoDb 3.6 or later, modernFindOne is called, otherwise legacyFindOne |
modernFindAndModify |
Tested | legacyFindAndModify |
The old method findandModify now is simply a wrapper. If you are running MongoDb 3.6 or later, modernFindAndModify is called, otherwise legacyFindAndModify |
modernAggregate |
Tested | legacyAggregateToStream |
The old method aggregateToStream now is simply a wrapper. If you are running mongoDb 3.6 or later, modernAggregate is called, otherwise legacyAggregateToStream |
modernAggregateCursor |
Tested | - | This method has no corresponding legacy one, as it returns a cursor and not a Map like the legacy aggregate |
- | Production | aggregate |
The legacy method aggregate has no corresponding "modern" method. It returns a Map. Is it used? |
watch | Tested | - | This method has no corresponding legacy methods. Allows to monitor changes in a collection. Examples: watch selecting records - watch all insert operations |
watchCursor |
Tested | - | This method has no corresponding legacy methods. Like watch , but returns a cursor instead of a stream. Normally you will only need watch |
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:
Command | Status | Legacy alternative | Notes |
---|---|---|---|
createIndex |
Production | db.createIndex |
This was needed because the legacy method didn't work any more starting from release 4.0 |
createCollection |
Tested | - | Explicitly creates a collection. Useful if you want to create a capped collection or assign a collation to the collection. |
createView |
Tested | - | Creates a view |
getParameterCommand |
Tested | - | Allows to get a specific server parameter |
getAllParametersCommand |
Tested | - | Returns all config parameters |
killCursorCommand |
Tested | MongoKillCursorMessage |
Used internally to close an unexhausted cursor. |
getMoreCommand |
Tested | MongoGetMoreMessage |
Used internally to read a new batch of data from the server |
getLastErrorCommand |
Tested | DbCommand.createGetLastErrorCommand |
Used internally to return the status of the previous operation. It is no more needed with the modern operations, but, for compatibility reasons, it can be used still. |
serverStatus |
Tested | serverStatus |
The method was already present, but it has been improved giving the possiblity to return a class with all the values instead of a map |