{"id":4914,"library":"couchbase","title":"Couchbase Python Client","description":"The Couchbase Python Client (SDK) is an official library for interacting with Couchbase Server and Couchbase Capella. It provides functionalities for data operations (CRUD), querying (N1QL, FTS, Analytics, Vector Search), and cluster management. The current major version is 4.x, built on a high-performance C++ backend. The library maintains an active development cycle with regular minor and patch releases delivering new features, improvements, and bug fixes.","status":"active","version":"4.6.0","language":"en","source_language":"en","source_url":"https://github.com/couchbase/couchbase-python-client","tags":["database","NoSQL","document database","key-value store","Couchbase","async"],"install":[{"cmd":"pip install couchbase","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.7 or later. Python 3.8 support has been dropped in recent SDK versions, and 3.9 will be dropped as it reaches EOL.","package":"python","optional":false},{"reason":"Required for installing from source if no pre-built binary wheel is available for your platform.","package":"C++17 compatible compiler, CMake >= 3.18, Git","optional":true},{"reason":"Required for SDK versions prior to 4.1.9. Versions 4.1.9 and later statically link BoringSSL, removing this direct requirement for binary wheels.","package":"OpenSSL 1.1","optional":true},{"reason":"Required if using the `txcouchbase` API for Twisted-based asynchronous operations.","package":"Twisted >= 21.7.0","optional":true}],"imports":[{"note":"The primary `Cluster` object for synchronous operations is now found directly under `couchbase.cluster`. Older SDKs might have had different paths.","wrong":"from couchbase.bucket import Cluster","symbol":"Cluster","correct":"from couchbase.cluster import Cluster"},{"note":"Connection options are found in `couchbase.options`.","wrong":"from couchbase.cluster import ClusterOptions","symbol":"ClusterOptions","correct":"from couchbase.options import ClusterOptions"},{"note":"Authentication classes are under `couchbase.auth`.","wrong":"from couchbase.cluster import PasswordAuthenticator","symbol":"PasswordAuthenticator","correct":"from couchbase.auth import PasswordAuthenticator"},{"note":"Options for N1QL queries are under `couchbase.options`.","symbol":"QueryOptions","correct":"from couchbase.options import QueryOptions"},{"note":"For `asyncio`-based asynchronous operations, use imports from `acouchbase.cluster`.","symbol":"acouchbase.cluster.Cluster","correct":"from acouchbase.cluster import Cluster, get_event_loop"},{"note":"When using `Twisted`, `txcouchbase` *must* be imported before the `twisted.internet.reactor` to ensure the `asyncio` reactor is installed.","symbol":"txcouchbase","correct":"import txcouchbase\nfrom twisted.internet import reactor\nfrom txcouchbase.cluster import TxCluster"}],"quickstart":{"code":"import os\nfrom couchbase.cluster import Cluster, ClusterOptions\nfrom couchbase.auth import PasswordAuthenticator\nfrom couchbase.exceptions import CouchbaseException\n\n# Get connection details from environment variables for security\nCONNECTION_STRING = os.environ.get('CB_CONNECTION_STRING', 'couchbase://localhost')\nUSERNAME = os.environ.get('CB_USERNAME', 'Administrator')\nPASSWORD = os.environ.get('CB_PASSWORD', 'password')\nBUCKET_NAME = os.environ.get('CB_BUCKET_NAME', 'default')\n\ndef main():\n    cluster = None\n    try:\n        # Connect to Couchbase Cluster\n        auth = PasswordAuthenticator(USERNAME, PASSWORD)\n        cluster_options = ClusterOptions(auth)\n        cluster = Cluster(CONNECTION_STRING, cluster_options)\n\n        # Wait for the cluster to be ready (optional but good practice)\n        # cluster.wait_until_ready(timedelta(seconds=5))\n\n        # Get a bucket and default collection\n        bucket = cluster.bucket(BUCKET_NAME)\n        collection = bucket.default_collection()\n\n        # Store a document\n        key = 'user:123'\n        value = {'name': 'Alice', 'age': 30, 'city': 'New York'}\n        result = collection.upsert(key, value)\n        print(f\"Upserted document '{key}', CAS: {result.cas}\")\n\n        # Retrieve the document\n        get_result = collection.get(key)\n        print(f\"Retrieved document '{key}': {get_result.content_as[dict]}\")\n\n        # Update a field in the document\n        updated_value = get_result.content_as[dict]\n        updated_value['age'] = 31\n        update_result = collection.upsert(key, updated_value)\n        print(f\"Updated document '{key}', new CAS: {update_result.cas}\")\n\n        # Delete the document\n        collection.remove(key)\n        print(f\"Removed document '{key}'\")\n\n    except CouchbaseException as e:\n        print(f\"Couchbase Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n    finally:\n        if cluster:\n            # Close the cluster connection (important for resource management)\n            cluster.disconnect()\n\nif __name__ == '__main__':\n    main()\n","lang":"python","description":"This quickstart demonstrates how to connect to a Couchbase cluster, perform basic CRUD (Create, Read, Update, Delete) operations on a document, and handle common exceptions. It uses environment variables for sensitive connection details. Ensure you have a Couchbase cluster running and a bucket available, with appropriate credentials."},"warnings":[{"fix":"Refer to the 'Migrating to SDK 3 API' documentation for a detailed migration guide.","message":"Migration from SDK 2.x to SDK 3.x/4.x involves significant API changes, including the removal of the `Document` class (now `Result` objects are returned) and the introduction of `Collections` and `Scopes` for data organization.","severity":"breaking","affected_versions":"< 3.0"},{"fix":"Thoroughly test existing applications when upgrading from 3.x to 4.x. Avoid relying on internal SDK mechanisms.","message":"The Couchbase Python SDK 4.x switched its backend from `libcouchbase` to `Couchbase++`. While the API surface aims for compatibility with SDK 3.x, code relying on undocumented internal details might break.","severity":"breaking","affected_versions":"All versions 4.0.0 and above, when migrating from 3.x"},{"fix":"Ensure `import txcouchbase` occurs before `from twisted.internet import reactor` in your code.","message":"When using the `txcouchbase` API for Twisted integration in SDK 4.x, the `txcouchbase` package *must* be imported before importing the Twisted reactor to ensure the `asyncio` reactor is properly installed.","severity":"breaking","affected_versions":"All versions 4.0.0 and above"},{"fix":"Initialize Couchbase connections within each child process. Consider using `atfork` module if necessary to manage resources during forking.","message":"Couchbase connection objects are not fork-safe. If using multiprocessing (e.g., with Gunicorn/uWSGI), ensure that `Cluster.connect()` (or similar connection initialization) is called *after* a child process has forked, not in the parent process.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to SDK version 4.1.9 or later. Alternatively, set the `PYCBC_OPENSSL_DIR` environment variable to the path where OpenSSL 1.1 libraries (`libssl-1_1.dll` and `libcrypto-1_1.dll`) can be found.","message":"Python 3.11.5+ on Windows uses OpenSSL 3.0. Couchbase Python SDK versions below 4.1.9 were built against OpenSSL 1.1, potentially causing `ImportError: DLL load failed while importing pycbc_core`.","severity":"gotcha","affected_versions":"< 4.1.9 (on Windows with Python 3.11.5+)"},{"fix":"Always use a currently supported Python version (3.10, 3.11, 3.12, 3.13, 3.14+). Refer to the 'Python Version Compatibility' documentation for the latest supported versions.","message":"The Couchbase Python SDK is dropping support for older Python versions as they reach their End-of-Life (EOL). Python 3.8 wheels are no longer provided, and Python 3.9 wheels will be removed in a future release (Python 3.9 reaches EOL in October 2025).","severity":"deprecated","affected_versions":"All versions (future updates)"},{"fix":"Rely on the SDK's default connection management for KV operations. Note that `config_poll_interval` for topology changes is configurable and defaults to 2.5 seconds.","message":"Direct configuration of KV/data service connection pooling is not currently supported, and options like `max_http_connections` passed to the C++ core are a no-op for these services.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}