CouchDB Python Library

Common errors

• couchdb.http.InvalidURL: Nonnumeric port

  cause This error typically occurs when the connection URL contains special characters (like ':' or '@') in the username or password fields that are not properly URL-encoded, or when the credentials are inserted in a way that the URL parser misinterprets parts of them as a port number.
  fix Ensure username and password parts of the URL are percent-encoded if they contain special characters. Alternatively, pass credentials separately if the client library supports it, or reconstruct the URL carefully. Example: `server = couchdb.Server(f'http://{requests.utils.quote(user)}:{requests.utils.quote(password)}@{host}:{port}/')`.

• AttributeError: module 'http' has no attribute 'client'

  cause This error (or similar ones related to `json` modules) can arise in earlier Python 3.x versions (before 3.4, which is officially unsupported by `couchdb` 1.2) due to naming conflicts between the `couchdb.http` and `couchdb.json` internal modules and Python's built-in `http` and `json` standard library modules.
  fix Upgrade to Python 3.4 or higher, which `couchdb` 1.2 officially supports and where many of these compatibility issues were addressed. If upgrading is not an option, consider using `python-cloudant`.

• couchdb.http.ResourceNotFound: ('not_found', 'missing')

  cause The specified database or document ID does not exist on the CouchDB server. This can happen if you try to access a database that hasn't been created or a document with an incorrect ID.
  fix Verify that the database name is correct and that it exists (`db_name in server`). For documents, double-check the `_id` you are using. If creating a new database, ensure `server.create(db_name)` is called.

Warnings

• breaking The `couchdb` Python library is no longer being actively maintained. Users are strongly encouraged to migrate to `python-cloudant` (IBM Cloudant's official library, compatible with Apache CouchDB) for continued support and new features.
  Fix: Migrate your application to use the `python-cloudant` library. Check its documentation for equivalent API calls.
• gotcha Avoid using `db.create()` for documents where an `_id` is not specified, allowing CouchDB to generate IDs. The underlying HTTP POST operation is not idempotent, and retries due to network issues can lead to duplicate documents being created. Always specify `_id` on the client side when saving documents.
  Fix: Explicitly set the `_id` field in your document dictionary before calling `db.save(doc)`.
• breaking Version 1.2 of `couchdb` removed support for Python 2.6 and Python 3.x versions older than 3.4. Attempting to use it with unsupported Python versions may lead to unexpected errors or installation failures.
  Fix: Ensure you are running Python 2.7 or Python 3.4+. For newer Python 3.x versions, while 1.2 fixed many issues, consider the `python-cloudant` alternative for full compatibility.
• gotcha When connecting to CouchDB version 3 or higher, it is mandatory to specify user credentials (username and password) in the connection URL to avoid `couchdb.http.Unauthorized` errors. The default `http://localhost:5984/` without credentials will not work.
  Fix: Provide credentials in the URL, e.g., `couchdb.Server('http://username:password@localhost:5984/')`. Ensure username and password are URL-encoded if they contain special characters.
• gotcha Document update conflicts (`couchdb.http.ResourceConflict` or `CouchDBDocumentConflict` if using `couchdb.mapping`) occur if you attempt to save a document without its latest `_rev` field. This happens when another process updates the document between your retrieval and save operations.
  Fix: Always retrieve the latest version of a document before making modifications and saving it back. Implement retry logic for conflicts if necessary.

Install

• pip install couchdb Install stable version

Imports

• Server

  import couchdb
  server = couchdb.Server('http://user:pass@host:port/')

• Database
  wrong:

  from couchdb.client import Database

  correct:

  db = server['mydb_name']

  While `couchdb.client` contains `Server` and `Database` classes, they are typically accessed via the top-level `couchdb` package and then instantiated or accessed through the `Server` object. Direct import of `Database` is less common for initial setup.

Quickstart

This quickstart demonstrates how to connect to a CouchDB server, create or access a database, save a document with a client-side ID, retrieve, update, and finally delete a document and the database. It includes basic error handling for common issues and uses environment variables for credentials, which is crucial for CouchDB 3.x and above.

import couchdb
import os

# Configure connection details, including authentication for CouchDB 3.x+
# Use environment variables for sensitive data in production
COUCHDB_URL = os.environ.get('COUCHDB_URL', 'http://localhost:5984/')
COUCHDB_USER = os.environ.get('COUCHDB_USER', 'admin')
COUCHDB_PASSWORD = os.environ.get('COUCHDB_PASSWORD', 'password')

# Construct the URL with credentials for CouchDB 3.x and above
# Note: ensure username/password are URL-encoded if they contain special characters
if COUCHDB_USER and COUCHDB_PASSWORD:
    auth_url = f'http://{COUCHDB_USER}:{COUCHDB_PASSWORD}@{COUCHDB_URL.split('//')[-1]}'
else:
    auth_url = COUCHDB_URL

try:
    server = couchdb.Server(auth_url)
    
    # Check if a database exists, create if not
    db_name = 'my_test_database'
    if db_name not in server:
        db = server.create(db_name)
        print(f"Database '{db_name}' created.")
    else:
        db = server[db_name]
        print(f"Connected to existing database '{db_name}'.")

    # Create and save a document
    doc = {'_id': 'mydoc1', 'name': 'John Doe', 'age': 30}
    db.save(doc)
    print(f"Document saved: {doc['_id']} (rev: {doc['_rev']})")

    # Retrieve a document
    retrieved_doc = db['mydoc1']
    print(f"Retrieved document: {retrieved_doc}")

    # Update a document (must have the latest revision)
    retrieved_doc['age'] = 31
    db.save(retrieved_doc)
    print(f"Document updated: {retrieved_doc['_id']} (new rev: {retrieved_doc['_rev']})")

    # Delete the document
    db.delete(retrieved_doc)
    print(f"Document '{retrieved_doc['_id']}' deleted.")

    # Delete the database (optional)
    del server[db_name]
    print(f"Database '{db_name}' deleted.")

except couchdb.http.ResourceNotFound as e:
    print(f"Error: Resource not found. Check database name or document ID. Details: {e}")
except couchdb.http.Unauthorized as e:
    print(f"Error: Authentication failed. Check COUCHDB_USER and COUCHDB_PASSWORD. Details: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")