Simple returner for CouchDB. Optional configuration settings are listed below, along with sane defaults:

couchdb.db: 'salt'
couchdb.url: 'http://salt:5984/'

Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location:

alternative.couchdb.db: 'salt'
alternative.couchdb.url: 'http://salt:5984/'

To use the couchdb returner, append --return couchdb to the salt command. Example:

salt '*' --return couchdb

To use the alternative configuration, append --return_config alternative to the salt command.

New in version 2015.5.0.

salt '*' --return couchdb --return_config alternative

To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.

New in version 2016.3.0.

salt '*' --return couchdb --return_kwargs '{"db": "another-salt"}'

On concurrent database access

As this returner creates a couchdb document with the salt job id as document id and as only one document with a given id can exist in a given couchdb database, it is advised for most setups that every minion be configured to write to it own database (the value of couchdb.db may be suffixed with the minion id), otherwise multi-minion targeting can lead to losing output:

  • the first returning minion is able to create a document in the database
  • other minions fail with {'error': 'HTTP Error 409: Conflict'}

This function makes sure that all the views that should exist in the design document do exist.


Return a dict with key being minion and value being the job details of the last run of function 'fun'.


Get the document with a given JID.


List all the jobs that we have..


Return a list of minion identifiers from a request of the view.


Returns a dict object of views that should be part of the salt design document.

salt.returners.couchdb_return.prep_jid(nocache=False, passed_jid=None)

Do any work necessary to prepare a JID, including sending a custom id


Take in the return and shove it into the couchdb database.


Helper function that sets the salt design document. Uses get_valid_salt_views and some hardcoded values.