Mongo Preview Release!

Mongo is a pure Fantom driver for MongoDB.

• Install: fanr install -r http://eggbox.fantomfactory.org/fanr/ afMongo
• Overview: http://eggbox.fantomfactory.org/pods/afMongo/
• Source: https://bitbucket.org/AlienFactory/afmongo

Mongo driver features:

• Standard and capped collections
• Write commands: insert(), update(), delete() and findAndModify() (v2.6+)
• Write concern support (v2.6+)
• Optimised queries for findOne() and findAll()
• Cursor support
• Aggregation commands: aggregate(), distinct(), group() and mapReduce()
• Index support: create(), ensure() and drop()
• User support: create(), drop(), grant() and revoke() roles
• Database authentication
• Server side eval() commands
• Pooled connection manager for multi-threaded use

Mongo driver has been written specifically for MongoDB v2.6.0, released on 8th April 2014, or newer.

Many features, including ALL write commands, will NOT work with older MongoDB versions.

Quick Start

1). Start up an instance of MongoDB:

C:\> mongod

MongoDB starting
db version v2.6.0
waiting for connections on port 27017

2). Create a text file called Example.fan:

using afBson
using afMongo
using concurrent

class Example {

    Void main() {
        mongoClient := MongoClient(ActorPool(), "127.0.0.1", 27017)
        collection  := mongoClient.db("friends").collection("birds")

        documentIn  := [
            "_id"   : ObjectId(),
            "name"  : "Emma",
            "score" : 9
        ]
        collection.insert(documentIn)

        echo( collection.findAll.first )

        mongoClient.shutdown
    }
}

3). Run Example.fan as a Fantom script from the command line:

C:\> fan Example.fan

     Alien-Factory
 _____ ___ ___ ___ ___
|     | . |   | . | . |
|_|_|_|___|_|_|_  |___|
              |___|0.0.2

Connected to MongoDB v2.6.0

[_id:5373acbda8000b3491000001, name:Emma, score:9]

Usage

MongoClient is the main entry point into Mongo. From there you can access all other components of MongoDB, namely Database, Collection, Index and User.

MongoClient
 `-- Database
      +-- Collection
      |    `-- Index
      `-- User

Connecting

MongoClient is created with a ConnectionManager, which manages your connections to MongoDB. Use ConnectionManagerPooled for normal multi-threaded use:

conMgr := ConnectionManagerPooled(ActorPool(), IpAddr("localhost"), 27017)
client := MongoClient(conMgr)

When you create a MongoClient it immediately connects to MongoDB and verifies it is the correct version:

.    Alien-Factory
 _____ ___ ___ ___ ___
|     | . |   | . | . |
|_|_|_|___|_|_|_  |___|
              |___|0.0.2

Connected to MongoDB v2.4.9

[warn] ****************************************************************************
[warn] ** WARNING: This driver is ONLY compatible with MongoDB v2.6.0 or greater **
[warn] ****************************************************************************

Ooops! As you can see, we have an old MongoDB running. And true enough, when we run the QuickStart example we get:

afMongo::MongoCmdErr: Command 'insert' failed. MongoDB says: no such cmd: insert

Installing a fresh MongoDB of version 2.6.0 or greater will get you back on track.

Queries

Mongo and MongoDB work with documents, they are used throughout the Mongo API. A MongoDB document is represented in Fantom as a Map of type [Str:Obj?]. All document keys must be strings. Document values can be any valid BSON type.

ALIEN-AID: See the upcoming Alien-Factory Morphia library for complete Fantom to MongoDB object mapping!

A MongoDB database stores documents in collections. Use the find() methods to query a collection. Using the friends database in the QuickStart Example we could do:

collection.findOne( ["name":"Emma"] )       // --> return the doc where 'name == Emma' 
                                            //     ('Emma' must be unique)

collection.findAll                          // --> return ALL docs in the collection
collection.findAll( ["name":"Emma"] )       // --> return all docs where 'name == Emma'
collection.findAll( ["score": ["\$gt":7]] ) // --> return all docs with 'score > 7'

The $gt expression is an example of a Query operator.

To iterate over a massive collection without loading it all into memory, use a Cursor. Cursors download documents in batches, behind the scenes, as and when required. Create and use a Cursors by using the find() method:

collection.find( ["score": ["\$gt":2]] ) |cursor| {
    cursor.batchSize = 10

    while (cursor.hasNext)
        doc := cursor.next
        ...
    }
}

Write Commands

The insert() command is simple enough and is demonstrated in the QuickStart example.

update() and delete() are similar in that they both take a query that describes which document(s) are to be updated / deleted. For most usages this will a simply be the id of the document in question:

collection.update( ["_id": objId], [ ...new doc...] )

Note that as of MongoDB v2.6 there is longer any need to call a getLastError() function. All error handling is done via write concerns. By default Mongo will throw a MongoErr should a write error occur.

ObjectId

All documents held in a collection need a unique id, held in a field named _id. If the _id field does not exist, MongoDB will create one for you of type ObjectId.

Note that _id does not need to an ObjectId, it can be any BSON type. It just needs to be unique in the collection.

Like marmite, people tend to have a love / hate relationship with the ObjectId. The good comments revolve around it having a natural sort that (roughly) corresponds to creation time. The bad is that in humongous collections it eats up precious bytes which means the index can't fit into RAM.

Remarks

The Alien-Factoy MongoDB driver was inspired by fantomongo by Liam Staskawicz.

Have fun!

: )

Excellent... Just on time :) I was just looking for it. Thanks

As afMongo is in its infancy, the documentation is quite light at the moment and assumes you know MongoDB. But hopefully for anyone who's used the Mongo Shell it should be pretty easy to follow.

Please lemme know if there are any glaring bugs or if anything is unclear.

For those needing a MongoDB v2.6 server out there, MongoLab offer v2.6 servers in their free "experimental" Sandbox plans. From a helpful reply to a support query, Dave says:

We have made MongoDB 2.6.1 available for our "experimental" Sandbox plans - just select the "experimental plan" option when you create your database. Experimental Sandboxes are only available in AWS us-east-1, AWS eu-west-1 and Azure West US.

He continues with an (reasonable) explanation to their production release process:

When MongoDB 2.2 and 2.4 were previously released, we did not support either for production databases until after a few maintenance releases. We want to make sure 2.6 has been battle-tested before rolling it out across our fleet. That being said, there's no definitive timeline but we anticipate a production-worthy release around 2.6.3 or 2.6.4.

We realize our approach to rolling out MongoDB version 2.6 for production may seem conservative but in our experience it is the proper decision.

Steve.