CouchDB - Deleting a Database

CouchDB - Deleting a Database

In CouchDB, deleting a database is an irreversible action that removes the database and all its documents, views, and attachments. This operation should be performed with caution. We’ll explore how to do this using the command-line cURL utility and the modern web interface, Fauxton.

Prerequisites: Authentication

Modern versions of CouchDB (3.x and later) are secure by default. All requests, including deleting a database, require administrator credentials. Throughout these examples, we’ll assume you have an admin user named admin with a password password. You would have configured this during setup.

Method 1: Using the cURL Command-Line Utility

You can delete a database by sending an HTTP DELETE request to the database’s endpoint. The cURL utility is a powerful tool for this.

The basic syntax is:

curl -u YOUR_ADMIN_USER:YOUR_ADMIN_PASSWORD -X DELETE http://127.0.0.1:5984/your_database_name

Let’s break down the command:

• -u YOUR_ADMIN_USER:YOUR_ADMIN_PASSWORD specifies the credentials for Basic Authentication. This is the modern, secure way to authenticate.
• -X DELETE specifies that we are sending an HTTP DELETE request.
• http://127.0.0.1:5984/your_database_name is the full URL to the database you wish to delete.

Example

Let’s say we have a database named test_db that we want to delete. The command would be:

$ curl -u admin:password -X DELETE http://127.0.0.1:5984/test_db

{
    "ok": true
}

A successful response from the server is a simple JSON object: {"ok": true}. This confirms that the database has been permanently removed.

Verification

To verify that the database is gone, you can request the list of all databases. The deleted database, test_db, should no longer appear in the list.

$ curl -u admin:password -X GET http://127.0.0.1:5984/_all_dbs

["_global_changes", "_replicator", "_users"]

Common Errors

If you try to delete a database that doesn’t exist, you’ll receive a 404 Not Found error:

{"error":"not_found","reason":"Database does not exist."}

If your credentials are wrong or not provided, you’ll get a 401 Unauthorized error:

{"error":"unauthorized","reason":"You are not a server admin."}

Method 2: Using Fauxton (The Web UI)

Fauxton is the official web-based interface for CouchDB, providing a user-friendly way to manage your databases. The old interface, Futon, is no longer used.

Follow these steps to delete a database using Fauxton:

• 1. Open your web browser and navigate to Fauxton at http://127.0.0.1:5984/_utils/. You will be prompted to log in with your admin credentials.
• 2. Once logged in, click on the ‘Databases’ icon (looks like a stack of cylinders) in the left-hand navigation pane.
• 3. This will display a list of all your databases. Find the database you want to delete in the list (e.g., test_db).
• 4. To the right of the database name, you will see several icons. Click on the trash can icon to initiate deletion.
• 5. A confirmation dialog will appear to prevent accidental deletion. It will ask you to type the name of the database to confirm. Type the database name and click the ‘Delete’ button.
• 6. The database will be removed from the list, confirming it has been deleted.