AnyEvent condvars

You may have noticed that many of the examples in the SYNOPSIS call "recv" on the condvar. You're allowed to do this under 2 circumstances:

Either you're in a main program,

Main programs are "allowed to call "recv" blockingly", according to the author of AnyEvent.

or you're in a Coro + AnyEvent environment.

When you call "recv" inside a coroutine, only that coroutine is blocked while other coroutines remain active. Thus, the program as a whole is still responsive.

If you're not using Coro, and you don't want your whole program to block, what you should do is call "cb" on the condvar, and give it a coderef to execute when the results come back. The coderef will be given a condvar as a parameter, and it can call "recv" on it to get the data. The final example in the SYNOPSIS gives a brief example of this.

Also note that "recv" will throw an exception if the request fails, so be prepared to catch exceptions where appropriate.

Please read the AnyEvent documentation for more information on the proper use of condvars.

The \%options Parameter

key=keyvalue

This lets you pick out one document with the specified key value.

startkey=keyvalue

This makes it so that lists start with a key value that is greater than or equal to the specified key value.

startkey_docid=docid

This makes it so that lists start with a document with the specified docid.

endkey=keyvalue

This makes it so that lists end with a key value that is less than or equal to the specified key value.

count=max_rows_to_return

This limits the number of results to the specified number or less. If count is set to 0, you won't get any rows, but you will get the metadata for the request you made.

update=boolean

If you set "update" to "false", CouchDB will skip doing any updating of a view. This will speed up the request, but you might not see all the latest data.

descending=boolean

Views are sorted by their keys in ascending order. However, if you set "descending" to "true", they'll come back in descending order.

skip=rows_to_skip

The skip option should only be used with small values, as skipping a large range of documents this way is inefficient (it scans the index from the startkey and then skips N elements, but still needs to read all the index values to do that). For efficient paging use startkey and/or startkey_docid.

You may also put subroutine references in the "success" and "error" keys of this hashref, and they will be called upon success or failure of the request.

Documents Are Plain Hashrefs

Convenience Functions

This is a short-cut for:

  AnyEvent::CouchDB->new($uri)

and it is exported by default. It will return a connection to a CouchDB server, and if you don't pass it a URL, it'll assume <http://localhost:5984/>. Thus, you can type:

  $couch = couch;

$db = couchdb($name_or_uri);

This function will construct an AnyEvent::CouchDB::Database object for you. If you only give it a name, it'll assume that the CouchDB server is at <http://localhost:5984/>. You may also give it a full URL to a CouchDB database to connect to.

This function is also exported by default.

Object Construction

This method will instantiate an object that represents a CouchDB server. By default, it connects to <http://localhost:5984/>, but you may explicitly give it another URL if you want to connect to a CouchDB server on another server or a non-default port.

$db = $couch->db($name)

This method takes a name and returns an AnyEvent::CouchDB::Database object. This is the object that you'll use to work with CouchDB documents.

Queries and Actions

This method requests an arrayref that contains the names of all the databases hosted on the current CouchDB server. It returns an AnyEvent condvar that you'll be expected to call "recv" on to get the data back.

$cv = $couch->info()

This method requests a hashref of info about the current CouchDB server and returns a condvar that you should call "recv" on. The hashref that's returned looks like this:

  {
    couchdb => 'Welcome',
    version => '0.7.3a658574'
  }

$cv = $couch->config()

This method requests a hashref of info regarding the configuration of the current CouchDB server. It returns a condvar that you should call "recv" on.

$cv = $couch->replicate($source, $target, [ \%options ])

This method requests that a $source CouchDB database be replicated to a $target CouchDB database. To represent a local database, pass in just the name of the database. To represent a remote database, pass in the URL to that database. Note that both databases must already exist for the replication to work. To create a continuous replication, set the continuous option to true.

Examples:

  # local to local
  $couch->replicate('local_db', 'local_db_backup')->recv;

  # local to remote
  $couch->replicate('local_db', 'http://elsewhere/remote_db')->recv

  # remote to local
  $couch->replicate('http://elsewhere/remote_db', 'local_db')->recv

  # local to remote with continuous replication
  $couch->replicate('local_db', 'http://elsewhere/remote_db', {continuous => 1})->recv

As usual, this method returns a condvar that you're expected to call "recv" on. Doing this will return a hashref that looks something like this upon success:

  {
    history => [
      {
        docs_read       => 0,
        docs_written    => 0,
        end_last_seq    => 149,
        end_time        => "Thu, 17 Jul 2008 18:08:13 GMT",
        missing_checked => 44,
        missing_found   => 0,
        start_last_seq  => 0,
        start_time      => "Thu, 17 Jul 2008 18:08:13 GMT",
      },
    ],
    ok => bless(do { \(my $o = 1) }, "JSON::XS::Boolean"),
    session_id      => "cac3c6259b452c36230efe5b41259c04",
    source_last_seq => 149,
  }

Scripts

couchdb-push

Push documents from the filesystem to CouchDB

Related Modules

Other CouchDB-related Perl Modules

Net::CouchDb, CouchDB::Client, POE::Component::CouchDB::Client, DB::CouchDB

View Servers

CouchDB::View - This lets you write your map/reduce functions in Perl instead of JavaScript.

The Original JavaScript Version

The GitHub Repository

The Antepenultimate CouchDB Reference Card

The Reason for Existence

The "MIT" License

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.