Listen to database changes
Since the 0.10 release of CouchDB, it’s possible to listen on db changes via the REST api.
The `couchdbkit.Consumer` object provides you a way to listen on these changes asynchronously (continuous changes) or just wait for one change (longpolling). You can of course just fetch changes since the last update sequence.
Create a consumer
To create a consumer, instantiate the `couchdbkit.Consumer` object like this.
>>> from couchdbkit import Server, Consumer >>> s = Server() >>> db = s.create_db(“mydb”) >>> c = Consumer(db)
A consumer object is initialized with the db instance on which you want to listen changes.
Fetch changes
>>> db.save_doc({}) {'rev’: ’1-967a00dff5e02add41819138abb3284d’, 'ok’: True, 'id’: 'e3453543865212eede756809f71436c5’} >>> db.save_doc({}) {'rev’: ’1-967a00dff5e02add41819138abb3284d’, 'ok’: True, 'id’: 'b0ec8a9287cc53b00c1d621720e8144d’} >>> c.fetch(since=0) {'last_seq’: 2, 'results’: [{'changes’: [{'rev’: ’1-967a00dff5e02add41819138abb3284d’}], 'id’: 'e3453543865212eede756809f71436c5’, 'seq’: 1}, {'changes’: [{'rev’: ’1-967a00dff5e02add41819138abb3284d’}], 'id’: 'b0ec8a9287cc53b00c1d621720e8144d’, 'seq’: 2}]}
Here we get all changes since the db has been created via `fetch` method of `Consumer` instance.
Listen for changes
There are 2 possibilities in CouchDB to listen for changes. You can wait until a change happen in the db (longpolling) and close connection or you can just listen on each changes events and handle them in one function.
To wait for a change you may want to use the `wait_once` function. To wait a change since the last sequence:
>>> c.wait_once(since=2) {'last_seq’: 3, 'results’: [{'changes’: [{'rev’: ’1-967a00dff5e02add41819138abb3284d’}], 'id’: '70958b546d1f214d221c6a16648d3a2b’, 'seq’: 3}]}
`wait_once` will wait until a change happen or until connection timeout. Using `timeout` args or `heartbeat` you can set timeout or keep connection open.
To listen on changes asynchronously and react on them, you have to use the `wait` method. This method using Python `asyncore` module, will wait on new changes lines and send these lines to the functions you registered as callaback :
>>> def print_line(line): ... print “got %s” % line ... >>> c.register_callback(print_line) >>> c.wait() # Go into receive loop
By default it will wait infinitely, connection is kept alive.
Filter changes
`wait_once` and `wait` method allow you to use design docs filter’s functions to filter changes. Ex:
>>> c.wait(filter_name=“mydesign/filtername”)
`filter_name` argument take the design doc name and filter function name as string.