Introduction to mongopool - Nim

Version 1.0.1

A simple pure-nim mongodb pooled client designed for use with threaded applications such as Jester <https://github.com/dom96/jester>__.

HOW TO USE

Import the library. But, you will also really want the bson <https://github.com/JohnAD/bson>__ library as well since you will be using BSON documents.

import mongopool
import bson

Connect to MongoDB using the 'connectMongoPool' procedure.

connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")

Grab a connection from that pool.

var db = getNextConnection()

Use it to do things! See the section called BASIC CRUD <#basic-crud>__ for quick examples.

var doc = db.find("mycollection", @@{"name": "jerry"}).returnOne()

Release the connection when done.

releaseConnection(db)

HOW TO USE (THREADED)

The whole point of this library is threaded application use. Two key things to keep in mind:

You must call connectMongoPool before the threading begins.
Once inside the thread, you must both call getNextConnection for the next available connection and call releaseConnection before finishing the thread.

Failing to call releaseConnection will keep the connection in-use even after the thread closes.

Here is an example that uses Jester to make a web site:

import jester
import mongopool
import bson

connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")

routes:
  get "/":
    #
    # get a connection:
    #
    var db = getNextConnection()
    #
    # doing something with it:
    #
    var doc = db.find("temp").returnOne()
    #
    # releasing it before the thread closes
    #
    releaseConnection(db)
    #
    resp "doc = " & $doc

BASIC CRUD

Some quick examples of how to Create, Read, Update, and Delete and their related functions. See the appendix references for more details.

CREATE

Example:

import mongopool
import bson
connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")
var db = getNextConnection()

let joe = @@{
  "name": "Joe",
  "age": 42
}
let personFinal = db.insertOne("people", joe)
echo "$1 was given an _id of $2".format(personFinal["name"], personFinal["_id"])

releaseConnection(db)

related functions: insertMany <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#insertmany>, insertOne <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#insertone>

READ (FIND)

import mongopool
import bson
connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")
var db = getNextConnection()

var docs = db.find("people", @@{"age": {"$gt": 21}}).sort(@@{"name": 1}).limit(10).returnMany()

for doc in docs:
  echo "name: $1, age $2".format(doc["name"], doc["age"])

releaseConnection(db)

related functions:

to start the query: find <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#find>__
to modify the query: limit <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#limit>, skip <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#skip>, sort <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#sort>__
to get results from the query: returnCount <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#returncount>, returnMany <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#returnmany>, returnOne <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#returnone>__

UPDATE

import mongopool
import bson
connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")
var db = getNextConnection()

var joe = db.find("people", @@{"name": "Joe"}).returnOne()
joe["age"] = 43
let ctr = db.replaceOne("people", @@{"_id": joe["_id"]}, joe)
if ctr == 1:
  echo "change made!"

releaseConnection(db)

related functions: replaceOne <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#replaceone>, updateMany <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#updatemany>

DELETE

import mongopool
import bson
connectMongoPool("mongodb://someone:secret@mongo.domain.com:27017/abc")
var db = getNextConnection()

var ctr = db.deleteMany("people", @@{"name": "Larry"})
echo "$1 people named Larry removed.".format(ctr)

releaseConnection(db)

related functions: deleteMany <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#deletemany>, deleteOne <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst#deleteone>

Credit

Large portions of this code were pulled from the nimongo project, a scalable pure-nim MongoDb. See https://github.com/SSPkrolik/nimongo

If you are doing batch processing or internally-asynchronous manipulation of MongoDb, I recommend using using nimongo rather than this library. nimongo can be a very powerful tool.

On the other hand, if you are using MongoDB from an application that is already doing it's own asynchronous threading and you need a driver that does NOT thread, but is instead friendly to already-existing threads with pooling, then this might be the better library.