{"id":7113,"library":"couchdb","title":"CouchDB Python Library","description":"The `couchdb` Python package provides a client library for working with Apache CouchDB. It offers modules for interfacing with CouchDB servers, managing design documents, mapping JSON documents to Python objects, and a Python-based view server. While version 1.2 was released in 2018, the library is officially no longer being maintained, and users are encouraged to consider `python-cloudant` as an alternative.","status":"abandoned","version":"1.2","language":"en","source_language":"en","source_url":"https://github.com/djc/couchdb-python/","tags":["database","NoSQL","CouchDB","client","document-oriented","abandoned"],"install":[{"cmd":"pip install couchdb","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used if installed, otherwise Python's built-in `json` module is used.","package":"simplejson","optional":true}],"imports":[{"symbol":"Server","correct":"import couchdb\nserver = couchdb.Server('http://user:pass@host:port/')"},{"note":"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.","wrong":"from couchdb.client import Database","symbol":"Database","correct":"db = server['mydb_name']"}],"quickstart":{"code":"import couchdb\nimport os\n\n# Configure connection details, including authentication for CouchDB 3.x+\n# Use environment variables for sensitive data in production\nCOUCHDB_URL = os.environ.get('COUCHDB_URL', 'http://localhost:5984/')\nCOUCHDB_USER = os.environ.get('COUCHDB_USER', 'admin')\nCOUCHDB_PASSWORD = os.environ.get('COUCHDB_PASSWORD', 'password')\n\n# Construct the URL with credentials for CouchDB 3.x and above\n# Note: ensure username/password are URL-encoded if they contain special characters\nif COUCHDB_USER and COUCHDB_PASSWORD:\n    auth_url = f'http://{COUCHDB_USER}:{COUCHDB_PASSWORD}@{COUCHDB_URL.split('//')[-1]}'\nelse:\n    auth_url = COUCHDB_URL\n\ntry:\n    server = couchdb.Server(auth_url)\n    \n    # Check if a database exists, create if not\n    db_name = 'my_test_database'\n    if db_name not in server:\n        db = server.create(db_name)\n        print(f\"Database '{db_name}' created.\")\n    else:\n        db = server[db_name]\n        print(f\"Connected to existing database '{db_name}'.\")\n\n    # Create and save a document\n    doc = {'_id': 'mydoc1', 'name': 'John Doe', 'age': 30}\n    db.save(doc)\n    print(f\"Document saved: {doc['_id']} (rev: {doc['_rev']})\")\n\n    # Retrieve a document\n    retrieved_doc = db['mydoc1']\n    print(f\"Retrieved document: {retrieved_doc}\")\n\n    # Update a document (must have the latest revision)\n    retrieved_doc['age'] = 31\n    db.save(retrieved_doc)\n    print(f\"Document updated: {retrieved_doc['_id']} (new rev: {retrieved_doc['_rev']})\")\n\n    # Delete the document\n    db.delete(retrieved_doc)\n    print(f\"Document '{retrieved_doc['_id']}' deleted.\")\n\n    # Delete the database (optional)\n    del server[db_name]\n    print(f\"Database '{db_name}' deleted.\")\n\nexcept couchdb.http.ResourceNotFound as e:\n    print(f\"Error: Resource not found. Check database name or document ID. Details: {e}\")\nexcept couchdb.http.Unauthorized as e:\n    print(f\"Error: Authentication failed. Check COUCHDB_USER and COUCHDB_PASSWORD. Details: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Migrate your application to use the `python-cloudant` library. Check its documentation for equivalent API calls.","message":"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.","severity":"breaking","affected_versions":"All versions, as of 2025-09-08"},{"fix":"Explicitly set the `_id` field in your document dictionary before calling `db.save(doc)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"1.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"CouchDB 3.x+"},{"fix":"Always retrieve the latest version of a document before making modifications and saving it back. Implement retry logic for conflicts if necessary.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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}/')`.","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.","error":"couchdb.http.InvalidURL: Nonnumeric port"},{"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`.","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.","error":"AttributeError: module 'http' has no attribute 'client'"},{"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.","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.","error":"couchdb.http.ResourceNotFound: ('not_found', 'missing')"}]}