Introduction to mongopool

ver 1.0.1

.. image:: https://raw.githubusercontent.com/yglukhov/nimble-tag/master/nimble.png :height: 34 :width: 131 :alt: nimble :target: https://nimble.directory/pkg/mongopool

.. image:: https://repo.support/img/rst-banner.png :height: 34 :width: 131 :alt: repo.support :target: https://repo.support/gh/JohnAD/mongopool

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

HOW TO USE

1. 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.

.. code:: nim

import mongopool
import bson

1. Connect to MongoDB using the 'connectMongoPool' procedure.

.. code:: nim

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

1. Grab a connection from that pool.

.. code:: nim

var db = getNextConnection()

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

.. code:: nim

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

1. Release the connection when done.

.. code:: nim

releaseConnection(db)

HOW TO USE (THREADED)

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

1. You must call connectMongoPool before the threading begins.

2. 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:

.. code:: nim

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:

.. code:: nim

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)

.. code:: nim

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

.. code:: nim

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

.. code:: nim

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.

Table Of Contents

1. Introduction to mongopool <https://github.com/JohnAD/mongopool>__

2. Appendices

   A. mongopool Reference <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-ref.rst> B. mongopool/errors Reference <https://github.com/JohnAD/mongopool/blob/master/docs/mongopool-errors-ref.rst>