backbone-couchdb is a plugin for Backbone.js that takes care of synching (Backbone-) Models and Collections automatically with a CouchDB instance. It makes heavy use of CouchDBs built-in Couchapp functionality. Normally it would be necessary to set up a webserver and a webapp (Rails, Sinatra, Django…) in order to persist Models. But with this plugin it is only needed to host Backbone Apps as Couchapp and the persistence layer is ready out of the box.
Since the App runs as a Couchapp, it is also capable of using the CouchDB _changes-feed which enables the App to receive real-time updates for Collections and Models. If this functionality is not needed it can be turned off easily.
All Backbone apps should work normally without any changes. Simply include backbone-couchdb.js with its dependencies into your project and configure the connector with your database infos.
As you can see you also need to create a new database in your CouchDB and a new design document that contains the following view (should be named “byCollection.js”):
In order to sync properly, all Collections need a url property (functions work as well). The url is then translated into the collection property that has been used in the example above. To learn how to use custom views and keys for Collections, have a look at the recipes.
If you set
Backbone.couch_connector.config.global_changes = true, the connector will automatically update your models with remote changes in near real time.
But first you also have to add a filter function to your design document. By default a filter function called
by_collection is used, which can look like this:
If you happen to use the
initialize function in your Collection, make sure that you also call its super function because the changes-feed initialization happens in the connector’s
You simply have to add this line as the first line of your initialize function:
For the basic usage of this plugin there is no need to know anything about CouchDB because it manages everything automatically. To write more advanced apps (real-world apps) a basic knowledge of CouchDB components such as views, keys and filters is needed. I therefore recommend reading the O’Reilly open source CouchDB book.
Views - Using a custom view for a Collection
By default all Collections will use the byCollection-view as described in usage. But often it is necessary to retrieve a more detailed list of of Models than the list of all Models of a certain type. In a todo-list you would for example only need to get all entries that were not yet marked as done:
The corresponding view (
not_done_tasks.js) looks like this:
Filters - Only sync changes that are important for a certain user
This is a very common use-case in chats (private messages). When a private message is sent, only the recipient should receive the update. I recommend using the built-in authentication of CouchDB with this jQuery-couchlogin plugin.
Our Collection, assuming that there are two collections (normal messages / private messages), needs to have a custom filter function that allows us to decide which updates should be send to the _changes-feed for which user.
The filter-function needs to be placed inside the filters-folder of the couchapp directory and needs to be named exactly like the name we specified in our collection (in this case
Add custom request parameters
In order to pass custom parameters to e.g. view-calls you can add parameters to the db-config of your collection. This includes
You can even add more parameters to a collection’s fetch call like this:
All these options are optional, of course :)
- Backbone.js (>= 0.5.1)
- jquery.couch.js (already included in each CouchDB instance)
Fixed a bug with empty key param
- CoffeeScript rewrite
- Backbone 5.1 support
- Collection#db and Model#db objects
- Custom view support
- Custom key support
- Various bugs fixed
- Started versioning ;)