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.

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

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:

The server will respond with a welcome message:

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:

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

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:

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:

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

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:

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

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:

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

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