Welcome to Ming Documentation

Ming is an Object Document Mapper (like an ORM but for Document based databases), for MongoDB. Ming extends pymongo providing:

  • Declarative Models
  • Schema Validation and Conversion
  • Schema Evolution
  • Pure InMemory MongoDB Implementation
  • Unit of Work
  • Identity Map
  • One-To-Many, Many-To-One and Many-To-Many Relations

Getting Started

To get started with Ming just install it with:

$ pip install ming

Connecting to MongoDB

Before we start, make sure you have a copy of MongoDB running. First thing needed to start using Ming is to tell it how to connect to our instance of mongod. For this we use the create_datastore() function, this function creates a connection to the MongoDB instance, replicaset or cluster specified by the given URL:

from ming import create_datastore
from ming.odm import ThreadLocalODMSession

session = ThreadLocalODMSession(

The ThreadLocalODMSession is the object all your models will use to interact with MongoDB and can be directly used to perform low-level mongodb oprations. While this provides no particular benefit over using pymongo directly it already permits to create and query documents:

>>> session.db.wiki_page.insert({'title': 'FirstPage',
...                              'text': 'This is my first page'})
>>> session.db.wiki_page.find_one({'title': 'FirstPage'})
{'_id': ObjectId('64135757bd1c2ce4e0454dfc'), 'title': 'FirstPage', 'text': 'This is my first page'}

Using Models

Now that we know how to connect to the Database we can declare models which will be persisted on the database their session is associated to:

from ming import schema
from ming.odm import FieldProperty
from ming.odm.declarative import MappedClass

class WikiPage(MappedClass):
    class __mongometa__:
        session = session
        name = 'wiki_page'

    _id = FieldProperty(schema.ObjectId)
    title = FieldProperty(schema.String(required=True))
    text = FieldProperty(schema.String(if_missing=''))

Models can be created by creating them and flushing their changes to the database. A Model can then be queried back with the Model.query.find() method:

>>> # Creating a Document is enough to register it into the UnitOfWork
>>> WikiPage(title='FirstPage',
...          text='This is my first page')
<WikiPage _id=ObjectId('64135757bd1c2ce4e0454dfd')
  title='FirstPage' text='This is my first page'>
>>> # Flush the unit of work to save changes on DB
>>> session.flush()
>>> wp = WikiPage.query.find({'title': 'FirstPage'}).first()
>>> wp
<WikiPage _id=ObjectId('64135757bd1c2ce4e0454dfc')
  title='FirstPage' text='This is my first page'>

To start working with Ming continue with the Ming ODM User Guide


To get help with using Ming, use the Ming Users mailing list or the TurboGears Users mailing list.


Yes please! We are always looking for contributions, additions and improvements.

The source is available on GitHub and contributions are always encouraged. Contributions can be as simple as minor tweaks to this documentation or to ming itself.

To contribute, fork the project and send a pull request.


See the Ming News / Release Notes for a full list of changes to Ming

Documentation Content

Indices and tables