version_migration.txt

=========================
Migration from 0.4 to 0.5
=========================

The version 0.5 not only changes the API but brings a lot of bug fix so,
you may really want to upgrade.

Presentation
------------

One of the main feature of MongoDB is speed. Why using MongoDB if libraries on
top of it are slow ? I created MongoKit to be as simple and faster as possible.

It appears that collection are really important and are used all the time when
we tend to use them dynamically.  And using dynamic collections with MongoKit
was a pain : there was too much code to write and many bugs underlying.

I noticed that I was using a lot the pymongo library in my code when I wanted
dynamic collection or quickly fetching raw data.  So, I decided to follow the
pymongo api for MongoKit.

Pymongo use the following scheme : `connection.database.collection`. Let's say
we have created many ``Doc`` object in a collection "migration" on the db "test":

    >>> from pymongo import Connection
    >>> con = Connection()
    >>> data = con.test.migration.find()
    >>> type(data.next()) is dict
    True

The issue here is that we get raw data. 

Let's create our ``Doc`` object so it look like this::
    
    >>> from mongokit import Document
    >>> class Doc(Document):
    ...    structure = {'title':unicode}

The `db_name` and `collection_name` are not hard explained in the object
declaration anymore. We just describe the validation schema. Then, we have
to fire a connection and register our ``Doc`` object ::

>>> from mongokit import Connection
>>> con = Connection()
>>> con.register([Doc])

Let's the BlogPost object seen in the introduction:

>>> con.register([BlogPost])
>>> blogpost = con.test.migration.BlogPost()
>>> blogpost['title'] = u'my title'
>>> blogpost['body'] = u'a body'
>>> blogpost['author'] = u'me'
>>> blogpost.save()

Note that this is quite the same as the current api. We just get the BlogPost object
via the collection. The main advantage of this approach is that we don't have to
bother about the collection.

You can simulate the current api behavior like this:

    class BlogPostDocument(Document): # <-- just rename the class by adding "Document"
        ...
    >>> con.register([BlogPostDocument]) # register the document
    >>> BlogPost = con.test.migration.BlogPostDocument()

    >>> blogpost = BlogPost()
    >>> blogpost2 = BlogPost()

Another advantage is the ability of using the collection dynamically without pain.
Let's say that we want to put all BlogPost into a user collection (so one collection
by user) :

>>> user_col = 'me'
>>> blogpost = con.test[user_col].BlogPost()

Quering is as simple as instanciating object. There's two way of fetching objects :

 * getting raw data (the pymongo's way)
 * getting instanciated object with all method defined (the mongokit way)

The first approach will produce only python dict and is very fast.
The second will wrap the data into the MongoDocument. This is useful if we defined
methods and want to use them.

Getting raw data :

>>> raw_data = con.test.migration.find()

Actually, all pymongo's method can be apply :
    
>>> con.test.migration.remove({})
>>> con.test.drop_collection('migration')

Getting instanciated objects :

>>> blogpost_cursor = con.test.migration.BlogPost.find()
>>> bp = blogpost_cursor.next()

We can apply MongoDocument methods (`validate`, `to_json` etc...)

>>> bp.validate()
>>> bp
{'body': u'a body', 'title': u'my title', 'date_creation': datetime.datetime(...), 'rank': 0, 'author': u'me'}

Other mongokit queries are available :

>>> blogpost_cursor = con.test.migration.BlogPost.fetch() # get only BlogPost

So, what changed ?
------------------

 * replace `MongoDocument` by `Document`. I changed the name in order to facilitate the migration. So there won't be surprises
 * uuid is False by default in the `save()` method (instead of True)
 * replaced `all()` by `find()`. This in order to keep consistancy with the pymongo driver
 * replace `one()` by `find_one().
 * remove `db_name` and `collection_name`. Instead, you have to register your object to the connection.
 * passing a dictionary in "fields" is now deprecated. The problem when passing a dictionary is that a dictionary is unordered. This might be a problem for compound keys. If you want to make compound keys indexes, you now need to pass a list of tuples::

    >>> from mongokit import *
    >>> class MyDoc(Document):
    ...     structure = {
    ...         'standard':unicode,
    ...         'other':{
    ...             'deep':unicode,
    ...         },
    ...         'notindexed':unicode,
    ...     }
    ...     
    ...     indexes = [
    ...         {
    ...             'fields':[('standard',INDEX_ASCENDING), ('other.deep',INDEX_DESCENDING)],
    ...             'unique':True,
    ...         },
    ...     ]

 * removed cascade (`belong_to`) and related features. MongoKit is writed to be fast and production ready. Adding such feature brings bugs and complication in maintainability. As far as I know, those features was not really used and there are easy to implemented. So, I removed them. This bring more less and cleaner code. If you don't know how to implement those features, send me a message on the mailing list, Bitbucket or Twitter and I'll write a tutorial.
 * dropped Mongodb auth support. I'm not happy with the way it was handled. I have to think on a better API. So, in order to avoid another API changed, I removed this feature. If you really need this feature, contact me so we can think a new API together.
 * last but not least : better integration with web framework. All that you have to do is to set a connection and register all your objects.