Product docs and API reference are now on Akamai TechDocs.
Search product docs.
Search for “” in product docs.
Search API reference.
Search for “” in API reference.
Search Results
 results matching 
 results
No Results
Filters
Using CouchDB 2.0 on Ubuntu 20.04
Traducciones al EspañolEstamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
CouchDB, a non-relational or “NoSQL” database, uses HTTP APIs and JSON documents, making its concepts more intuitive to those familiar with web technologies. These also make CouchDB simple to integrate with web and mobile applications.
This guide shows you how to get started with CouchDB using its web interface—Fauxton—before diving into the basics of using the HTTP API and integrating it into a basic application.
Before You Begin
If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.
Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
Install CouchDB. Follow the instructions in the guide on How to Install CouchDB on Ubuntu 20.04 .
sudo
. If you’re not familiar with the sudo
command, see the Linux Users and Groups
guide.Access the Fauxton Web Interface
The easiest way to configure and maintain your CouchDB installation is through its web interface, Fauxton. From a web browser on the machine where CouchDB is installed, you can access Fauxton by navigating to 127.0.0.1:5984/_utils
.
However, if you are accessing the machine remotely, the simplest and most secure way to access Fauxton is by using SSH tunneling. The following steps show you how to create and use an SSH tunnel for this purpose.
Follow the Access Futon Over SSH to Administer CouchDB guide to creating an SSH tunnel between your CouchDB server and the machine you are wanting to access it from.
In a web browser, navigate to
127.0.0.1:5984/_utils
.Log in to CouchDB using the administrator password you set up during the CouchDB installation. The default username for this user is
admin
.
Navigate Fauxton
Once you have logged into Fauxton, you are presented with a list of your CouchDB databases. Initially, this should only contain a
_users
and a_replicator
database. These are the two default system databases used by CouchDB.You can use the menu on the left to navigate the variety of configuration and monitoring options Fauxton offers. This menu also provides a Documentation option, where you can find numerous links to CouchDB and Fauxton documentation libraries.
There are two important actions not presented in the menu on the left:
- Creating a database
- Adding documents to a database.
The following steps show you how to take these actions using Fauxton.
Create a Database
Click the Create Database button on the upper right.
You are presented with a menu to enter the database name and select whether or not you want it partitioned.
Once you have created the database, you are taken to its page.
You can reach any particular database’s page via the Databases option on the menu on the left. The resulting page presents a list of databases from which you can select the desired database.
Add a Document
Go to the page for the database that you want to add a document to.
Click the + icon beside the All Documents option. From the dropdown menu, select New Doc.
You are taken to the new document editor, where you can input the JSON for a new CouchDB document.
Use the HTTP API
CouchDB’s HTTP API is the primary means for applications to interact with your databases. From the command line, you can use cURL to explore the API and even to quickly view and make changes to data within CouchDB.
The following commands are some examples of what you can do using the HTTP API. Replace admin
and password
with the username and password, respectively, for an authorized CouchDB user. These commands assume you are connected to the CouchDB machine either by SSH or an SSH tunnel, as described above.
Refer to CouchDB’s API guide for a full listing of API endpoints, parameters, and capabilities.
HTTP Queries
View the list of all databases.
curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs
Create a new database using the following command; replace
new-example-db
with the name for the new database.curl -X PUT http://admin:password@127.0.0.1:5984/new-example-db
View the list of all documents in the
example-db
database by using the following command:curl -X GET http://admin:password@127.0.0.1:5984/example-db/_all_docs
Add a document to the
example-db
database; replace the JSON after the-d
option with the desired JSON content for the document.curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db \ -d '{"key1":"value1","key2":"value2"}'
Note CouchDB automatically assigns an ID to the document if you do not explicitly provide one. However, CouchDB recommends that production applications create document IDs explicitly. Doing so prevents duplication of documents if your application has to retry its connection to the CouchDB database.The above command returns an ID corresponding to the new document. Likewise, the
_all_docs
command gives the ID for each document it lists. These IDs can be used to access the identified document by replacingid-string
with the ID for the desired document.curl -X GET http://admin:password@127.0.0.1:5984/example-db/id-string
Query Server
For more advanced queries, CouchDB has a query server. The query server takes search criteria in a JSON format and returns matching documents, or even a particular set of fields from matching documents.
The URL for the query server follows the same format as the URLs above. To query the example-db
database, for instance, you direct a POST
request to http://admin:password@127.0.0.1:5984/example-db/_find
with your JSON search criteria as the payload.
The following are examples of basic queries aiming to provide an idea of how the JSON search criteria work. Refer to CouchDB’s reference documentation for the _find
API
for a full list of criteria parameters and more details on their usage.
To retrieve all documents from
example-db
wherekey_1
is greater than five.curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db/_find \ -d '{"selector": {"key_1": {"$gt": 5}}}'
The operator options include:
$eq
(for “is equal to”)$lt
(for “is less than”) in addition to$gt
(for “is greater than”).
Some of CouchDB’s combination operators allow you to conduct boolean and other more advanced searches. Here is another example, which retrieves documents where
key_1
is between five and ten.curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db/_find \ -d '{"selector": {"$and": [{"key_1": {"$gt": 5}}, {"key_1": {"$lt": 10}}]}}'
Here is one that retrieves documents where
key_1
is greater than five or wherekey_2
equals “Example String”.curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db/_find \ -d '{"selector": {"$or": [{"key_1": {"$gt": 5}}, {"key_2": {"$eq": "Example String"}}]}}'
Use the following to define the specific fields to be returned from the matching documents and to sort the results by a specific field. In this case, the query server only returns the
key_2
field from the matching documents and sorts the results by thekey_3
field’s values.curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db/_find \ -d '{"selector": {"key_1": {"$gt": 5}}, "fields": ["key_2"], "sort": [{"key_3": "asc"}]}'
Note To sort results, you must first define an index for the field and the sort order. For the example above, you could use the following to create the necessary index:
curl -H 'Content-Type: application/json' \ -X POST http://admin:password@127.0.0.1:5984/example-db/_index \ -d {"index": {"fields": [{"key_3": "asc"}]}, "name": "example-index", "type": "json"}
Usage Examples
CouchDB shines in its straightforward integration with web applications. The following examples aim to demonstrate this by using CouchDB for a simple messaging application. The examples are written in pseudo-code, and they should be readily adaptable to the most popular programming languages for web applications.
You can find the small dataset used in these examples here
. If you would like to follow along, you can import the dataset using the following cURL command. Make sure you are in the same directory as the example-db.json
file and make sure you have already created the messaging-db
database used in the following examples:
curl -H 'Content-Type: application/json' \
-X POST http://admin:password@127.0.0.1:5984/messaging-db/_bulk_docs \
-d @example-db.json
The dataset already includes a custom index for sorting by a
date_time
field. However, for reference in creating your indices, here is the JSON used to generate this index. You can execute it using a cURL command like the one in the note above:{ "index": { "fields": [ {"date_time": "desc"} ] }, "name": "messaging-index", "type": "json" }
The application initially sets up a couple of variables that are to be referenced in each query.
- File: Example Messaging Application
1 2 3
db_query_headers = {"Content-Type": "application/json"} db_query_url = "http://admin:password@127.0.0.1:5984/messaging-db/_find"
When a user accesses a message thread, the application fetches the two most recent messages.
- File: Example Messaging Application
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
db_request = { "selector": { "$and": [ { "type": { "$eq": "message" } }, { "thread_id": { "$eq": "thread-0001" } } ] }, "fields": [ "user_id", "date_time", "message_body" ], "sort": [ {"date_time": "desc"} ], "limit": 2 } db_response = http_post_request(db_query_url, db_request, db_query_headers)
When a user sends a new message, the application inserts it as a new document.
- File: Example Messaging Application
1 2 3 4 5 6 7 8 9 10 11
db_request = { "_id": "message-00000006", "type": "message", "thread_id": "thread-0001", "user_id": "user-000001", "date_time": "2021-02-05 10:57:00", "message_body": "Example message text from user-000001, the first." } db_response = http_post_request(db_query_url, db_request, db_query_headers)
Next Steps
With that, you are ready to get started using CouchDB in your applications.
CouchDB has many more features than those demonstrated here, making it capable of handling a wide array of applications. You can easily begin to extend on the examples in this guide by referencing CouchDB’s exceptional repository of Apache CouchDB Documentation . Be sure to also explore the links provided in this guide and the documentation listing in your Fauxton interface.
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on