Working with CouchDB from the command line

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 Cloud Server (Ubuntu 16.04) with CouchDB installed.
Free Cloud Server Trial
Try our cloud hosting free for 30 days

Thanks to free starting credit, you can test the IONOS cloud server for 1 month free of charge (or until the credit is used up) and experience the perfect combination of performance and security!

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 a database or a document

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!"}'

Retrieve and read information about a database or a document

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 a document

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"}

Delete a record

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"}
Was this article helpful?
We use cookies on our website to provide you with the best possible user experience. By continuing to use our website or services, you agree to their use. More Information.
Page top