Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: a16bc458ea
Fetching contributors…

Cannot retrieve contributors at this time

111 lines (79 sloc) 3.59 KB


Couchtato is a CouchDB database iterator tool.

This is handy when you want to apply a set of JavaScript functions against all documents in a CouchDB database, or only some of them by specifying a start and/or an end document ID. On each JavaScript function, you can save a document, remove a document, log a message, or count the documents.

Performance and resource utilisation can be tuned by tweaking how many documents to retrieve per retrieval page, how many documents to update/remove per bulk update, and how many milliseconds interval between retrieval pages.


npm install -g couchtato


Create sample couchtato.js configuration file:

couchtato config

Iterate through all documents in a CouchDB database:

couchtato iterate -u http://user:pass@host:port/db

Iterate through documents within a range of IDs:

couchtato iterate -u http://user:pass@host:port/db -s Astartkey -e Zendkey

Only iterate the first 5 pages in the database where each page contains 1000 documents:

couchtato iterate -u http://user:pass@host:port/db -n 5 -p 1000

Save/remove docs in bulk of 20000 documents at a time:

couchtato iterate -u http://user:pass@host:port/db -b 20000

Pause for 5 seconds between each page retrieval:

couchtato iterate -u http://user:pass@host:port/db -i 5000


Specify the task functions in couchtato.js config file. Each function in exports.conf.tasks will be applied to each retrieved document one by one.

exports.conf = {
    "tasks": {
        "log-all-docs": function (util, doc) {
        "log-by-criteria": function (util, doc) {
            if (doc.title.match(/^The/)) {
        "update-by-criteria": function (util, doc) {
            if (doc.status === 'new') {
                doc.owner = 'Bob McFred';
        "delete-by-criteria": function (util, doc) {
            if (doc.status === 'spam') {
        "count-by-field": function (util, doc) {
        "whatever": function (util, doc) {
            // you need to implement whatever function

Note that you can also require other NodeJS modules in the config file if you need to.

The util variable

That 'util' in function (util, doc) is a utility variable, it provides you with the following convenient functions:

# save the document back to the database

# remove the document from the database

# increment a counter associated with a particular key
# all counters will be displayed in the summary report

# log a message to both the console and to couchtato.log file
# if you only want to display a message on the console,
# simply use good old console.log(message)


A summary report will be displayed at the end of the run:

Retrieved 2601388 documents in 5203 pages
Processed 10356 saves and 302 removes
- New data count: 1012
- Moderated data count: 4578
- Flagged data count: 88
Jump to Line
Something went wrong with that request. Please try again.