Working With CouchDB From the Command Line

Leave your reply

Introduction

Learn how to use the Curl utility to work with CouchDB from the command line. Although the Futon web admin interface is an easy way to perform simple operations with CouchDB, the API is the most flexible, fast, and powerful way to perform standard CRUD (Create, Read, Update, Delete) operations in CouchDB, both by hand and with scripts.

Requirements

  • A Servidor Cloud (Ubuntu 16.04) with CouchDB installed.

To install CouchDB, follow the instructions in our article Install and Use CouchDB on Ubuntu 16.04.

The Basics of Working With CouchDB

After you have installed CouchDB, you can access its API via HTTP on port 5984, using standard GET and PUT requests.

From the command line, you can use Curl to issue these requests.

You can test this with the command:

curl http://127.0.0.1:5984/

The server will respond with a welcome message:

{"couchdb":"Welcome","uuid":"f33e87d034bb8c1227f866445a977555","version":"1.6.1","vendor":{"version":"16.04","name":"Ubuntu"}}

Use the -X flag to specify a method (like GET or PUT) for Curl. For example, the command to get a list of all of the databases in the CouchDB installation is:

curl -X GET http://127.0.0.1:5984/_all_dbs

Create

Use the PUT method to create a database or a document (record). For example, to create a database named reviews the command is:

curl -X PUT http://127.0.0.1:5984/reviews

To add a document to the database, use curl -X PUT with the name of your database and the unique ID of the record you want to create, then use -d to pass along the record's information in JSON format.

For example, the following command will insert a record with ID 01 into the reviews database:

curl -X PUT http://127.0.0.1:5984/reviews/01 -d '{"reviewer_name":"Ben", "stars":"4", "details":"Love the calzone!"}'

Read

Use the GET method to retrieve and read information about a database or a document. To GET a document, specify the document's ID at the end of the URL.

For example, the command to retrieve the record we inserted in the example above is:

curl -X GET http://127.0.0.1:5984/reviews/01           

The server will respond with the document's contents in JSON format:

{
"_id":"01",
"_rev":"1-8ce1d23b7455705c3c2cbeeb86d8ccf5",
"reviewer_name":"Ben",
"stars":"4",
"details":"Love the calzone!"
}

Update

CouchDB has automatic revision tracking and control. In the example above, note that there is a _rev field with a revision number, even though we did not insert that in our original PUT request. This revision number field is automatically created each time you insert a record.

In order to update a document, you will need to tell CouchDB which revision you are updating. If the revision number matches, CouchDB will update the information and generate a new revision number. (If the revision number does not match, CouchDB will return a 409 conflict error.)

To update a document, use the PUT method, and include the revision number. You can either update the entire document or just a single field.

In this example, we will update the number of stars in the rating from 4 to 5:

curl -X PUT http://127.0.0.1:5984/reviews/01 -d '{"_id":"01", "stars":"5", "_rev":"1-8ce1d23b7455705c3c2cbeeb86d8ccf5"}'    

The server will return a response that includes "ok" and the new revision number:

{"ok":true,"id":"01","rev":"2-55b1c6edb9a0fd8eb58bd73b8e0058d5"}

&lt;a id=&quot;id7&gt;</a>

Delete

To delete a record, use the DELETE method and include the record's ID and most current revision number. For example, the command to delete the record we created above is:

curl -X DELETE http://127.0.0.1:5984/reviews/01?rev=2-55b1c6edb9a0fd8eb58bd73b8e0058d5

The server will return a response that includes "ok" and the new revision number:

{"ok":true,"id":"01","rev":"3-ec3f3491444854d08aaa7dd6ffe68670"}

This is because, in order to preserve CouchDB's replication functions, records are not actually deleted. Instead, a revision is added which includes information about the deletion, and the record will not be accessible with a standard request.

For example, if we try to view that record again, the server will respond with "not found":

user@localhost:$ curl -X GET http://127.0.0.1:5984/reviews/01
{"error":"not_found","reason":"deleted"}