A newer version of this documentation is available.

View Latest

Couchbase Python SDK Release Notes and Archives

Release notes, installation instructions, and download archive for the Couchbase Python Client.

The Couchbase Python SDK 3.0 is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 6.5 & 6.6 as a developer preview).

The 3.0 Python SDK introduces comprehensive PEP-484 style type annotations.

Requirements

Couchbase Python SDK bundles libcouchbase automatically, so no need to install it separately. You may need CMake to install, although the installer will attempt to download it from PyPI automatically.

The Python SDK 3.0 requires Python 3, with Python 3.5 and above supported.

Because the Python SDK is written primarily in C using the CPython API, the official SDK will not work on PyPy.

Installation

You may install previous versions of the SDK using pip (after installing the required dependencies)

$ python3 -m pip install git+https://github.com/couchbase/couchbase-python-client@VERSION

where VERSION is the version you wish to install. For example, to install version 2.5.4:

$ python3 -m pip install git+http://github.com/couchbase/[email protected]

Currently the Python Client source distribution requires the OpenSSL headers and libraries that the Python client itself was built against to be installed prior to the client itself for TLS support to be provided. Additionally the installer relies on PEP517 which older versions of PIP do not support. If you experience issues installing it is advised to upgrade your PIP/setuptools installation as follows:

$ python3 -m pip install --upgrade pip setuptools wheel

Installing on Linux

  • Debian and Ubuntu

  • RHEL and CentOS

During first-time setup:

$ sudo apt-get install git-all python3-dev python3-pip python3-setuptools cmake build-essential

For TLS/SSL support (optional):

$ sudo apt-get install libssl-dev

Now install the latest Python SDK:

$ python3 -m pip install couchbase

During first-time setup:

$ sudo yum install gcc gcc-c++ python3-devel python3-pip cmake
You may need to update your installed version of CMake. For example, by following the steps here.

For TLS/SSL support (optional):

$ sudo yum install openssl-devel

Now install the latest Python SDK:

$ python3 -m pip install couchbase
RHEL/CentOS distributions may not provide the python3-pip package in the base repositories. It may be found in the EPEL repository.

Installation on Mac OS X

The following example uses the Python supplied by the Homebrew package manager and not the vendor-supplied Python which ships with OS X.

To install the library on Mac OS X, first install Homebrew: Homebrew. Once Homebrew is configured:

Later versions of Mac OS X break the python3 homebrew installer. Simple mitigating steps may be found here.

Best practice is to use a Python virtual environment such as venv or pyenv to manage multible versions of Python, but in cases where this is not practicable follow the brew steps below, and also modify your $PATH as shown.

Get a list of the latest packages
$ brew update
Install compatible Python 3
$ brew install python3
For ZSH (MacOS 10.15 Catalina and newer)
$ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.zshrc
For BASH (MacOS 10.14 Mojave and older)
$ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.bash_profile
For TLS/SSL support - optional
$ brew install openssl
Installing the SDK
$ sudo -H python3 -m pip install couchbase

Installing on Microsoft Windows

$ python3 -m pip install couchbase

The standard Python distributions for Windows include OpenSSL DLLs, as PIP and the inbuilt ssl module require it for correct operation. The binary wheels for Windows are packaged as a binary wheel built against the relevant version OpenSSL (which is fixed per Windows version of Python).

If you require a version without OpenSSL support, or that doesn’t have a suitable binary wheel on PyPi, follow the build instructions on the GitHub repo.

Upgrading to 3.x

Python SDK 3.x automatically bundles libcouchbase (downloading and building it if necessary). Generally, there is no need to download and install it separately, and we recommend using the built-in libcouchbase. There are binary Python wheels provided for Windows.

Version 3.0.10 (4 March 2021)

$ python3 -m pip install couchbase==3.0.10

API Docs: http://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.10/

Fixes

  • PYCBC-865: Cluster-level ping will now use cluster, instead of open bucket.

Enhancements

  • PYCBC-1073: SDK now supports the Scopes & Collections API Changes in Server 7.0 beta.

Version 3.0.9 (2 February 2021)

$ python3 -m pip install couchbase==3.0.9

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.9/

Behavioral Change

This release deprecates a field on responses that show the expiration as a duration replacing it with an expiryTime which represents an instant point in time as a UNIX timestamp. It also introduces warnings when the duration specfied is likely an incorrect use of the API.

Fixes

  • PYCBC-968: Refactored Document Expiry Duration.

  • PYCBC-999: Deprecated GetResult.expiry().

Known Issues

  • PYCBC-1094: The new expiryTime field is returning a float to represent the expiration, rather than a datetime. Discovered too late for 3.0.9, this will be fixed in the next release.

Version 3.0.8 (13 January 2021)

$ python3 -m pip install couchbase==3.0.8

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.8/

Fixes

  • PYCBC-949: PasswordAuthenticator no longer fails with the optional cert_path argument.

  • PYCBC-969: Implemented SearchScanConsistency to replace QueryScanConsistency in the Search Service.

  • PYCBC-1078: Design doc unprefix was trimming off too many characters. A change in the unprefix method has fixed this.

Enhancements

Known Issues

  • PYCBC-1037: KV and Query latency are ~30% higher than SDK 2.x with external libcouchbase installed. Workaround: Remove any externally-installed libcouchbase releases from the system; when run with the built-in libcouchbase, the higher latency is not observed.

Version 3.0.7 (8 December 2020)

$ python3 -m pip install couchbase==3.0.7

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.7/

Fixes

  • PYCBC-587: Flask references returned to the introductory docs.

  • PYCBC-797, PYCBC-836, PYCBC-1045: Bucket.ping timeout can now be set as an option, following use of new lcb_cmdping_timeout from libcouchbase. Bucket.ping timeout on some remote nodes also fixed by this, as is the previous lack of an error enum status for PingState.

  • PYCBC-1030: collection_name and scope_name added to User Roles.

  • PYCBC-1033: Exception on six import fixed.

  • PYCBC-1038: Fix to handle change in how existing scope is reported by Couchbase Server 7.0.

  • PYCBC-1056: MutateIn was broken for all flavors of async. Now fixed for asyncio and for tested twisted uses.

Enhancements

  • PYCBC-1063: Intermittent fail in CollectionsTests.test_unlock_wrong_cas has been fixed.

Version 3.0.6 (3 November 2020)

Version 3.0.6 is the seventh release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.6

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.6/

Fixes

  • PYCBC-976: Added AnalyticsScanConsistency.

  • PYCBC-1019: Fixed a memory leak in N1QL Query.

  • PYCBC-1047: Updated namespace key for ping test to match change in libcouchbase. Ping test now works again.

  • PYCBC-1048: Collection tests were failing against upcoming 7.0 Server owing to changes in how the exceptions are structured or nested. Changed now to parse the HTTP error context’s result_body first, and improved the test suite for these and other services.

Enhancements

  • PYCBC-822: Added documentation on Certificate Authentication and LDAP.

  • PYCBC-1057: Subdoc expiry intermittent test fails fixed.

  • PYCBC-961: Added Options To Use FTS Hints (Flex Index).

  • PYCBC-963: Added Ephemeral Bucket Management Support.

Version 3.0.5 (4 September 2020)

Version 3.0.5 is the sixth release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.5

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.5/

Fixes

Enhancements

  • PYCBC-1011: If tests.ini not in current dir, now uses base path of PYCBC distro.

  • PYCBC-1016: Reenabled non-hybrid build for CLion.

Version 3.0.4 (11 August 2020)

Version 3.0.4 is the fifth release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.4

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.4/

Fixes

  • PYCBC-915: Remove support for Python <3.5.

  • PYCBC-951: The MutateInOptions don’t have durability.

  • PYCBC-986: Expose and document 'condition' parameter used to create partial N1QL indices.

  • PYCBC-989: Add xattr flag to SD.upsert.

  • PYCBC-954: Can’t query in the cloud.

  • PYCBC-983: Make Conan/PyGithub deps contingent on build reqs, enable 3.5 support.

  • PYCBC-984: Some N1QL query settings may not get set.

  • PYCBC-987: ImportError: DLL load failed: The specified module could not be found. - SSL.

  • PYCBC-988: Update release notes generator.

  • PYCBC-994: Remove error_map test as fetching is now automatic

  • PYCBC-1001: "Could NOT find PythonLibs (missing: PYTHON_LIBRARIES)" causing PEP517 install error.

  • PYCBC-1002: Explicitly set adhoc to off with lcb_cmdquery_adhoc and prepared statements.

Enhancements

  • PYCBC-671: Add Amazon Linux 2 verification testing.

  • PYCBC-933: Review docs for update items, identify/file issues.

  • PYCBC-992: Pin LCB to 3.0.3

  • PYCBC-998: SSL install notes update.

Version 3.0.3 (15 July 2020)

Version 3.0.3 is the fourth release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.3

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.3/

Fixes

Version 3.0.2 (14 July 2020)

Version 3.0.2 is the third release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.2

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.2/

Fixes

  • PYCBC-920: Twisted api seeing lots of timeouts.

  • PYCBC-941: Build against correct OpenSSL version on Windows.

  • PYCBC-950: N1QL query connections remain open after completion.

  • PYCBC-970: Python SDK assumes docstrings are available.

Enhancements

  • PYCBC-885: FTS Doc for Python 3.0.

  • PYCBC-929: Document how to get encrypted connections to clusters.

  • PYCBC-591: Document analytics using the Python SDK at draft level.

Version 3.0.1 (12 June 2020)

Version 3.0.1 is the second release of the 3.0 series, bringing enhancements and bug fixes over the last stable release.

$ python3 -m pip install couchbase==3.0.1

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.1/

Enhancements

Bug Fixes

  • PYCBC-714: Python SDK throwing SystemError.

  • PYCBC-833: get_all_replicas segfaults.

  • PYCBC-834: Intermittent segfault in collection.exists.

  • PYCBC-912: Generated docs need a second pass.

  • PYCBC-918: Version 3 needs access to bucket "default" to connect.

  • PYCBC-924: CBCollection.new invoking type superconstructor on some platforms.

  • PYCBC-928: Bootstrap timing out on Centos.

  • PYCBC-930: Using cert_path= in ClusterOptions hit inner_cause='cert_path' is an invalid keyword argument for this function, C Source=(src/bucket.c,1047).

  • PYCBC-934: Some Query OptionBlocks not passing kwargs to constructor.

  • PYCBC-936: QueryScanConsistency object should be an Enum.

  • PYCBC-937: Rename CBAS to ANALYTICS/Analytics to match LCB/RFC.

  • PYCBC-939: Unpin some dev_requirements entries.

Version 3.0.0 (1 May 2020)

This is the first GA release of the third generation Python SDK.

$ python3 -m pip install couchbase==3.0.0

API Docs: https://docs.couchbase.com/sdk-api/couchbase-python-client-3.0.0/

Whilst we have made our best efforts to update the API documentation to accurately reflect the functionality provided, there are still some known documentation issues to be resolved. We aim to fix these as soon as possible.

Known issues

  • PYCBC-912 Generated docs need a second pass.

  • PYCBC-834 Intermittent segfault in collection.exists.

  • PYCBC-833 get_all_replicas segfaults.

And an issue in libcouchbase that impacts upon the Python Client:

  • CCBC-128 Segfault in lcbtrace_span_add_tag_uint64.

Enhancements

  • PYCBC-816: Migrate txcouchbase to SDK3.

  • PYCBC-805: Provide async access to Cluster.

  • PYCBC-658: Provide txcouchbase support for durability.

  • PYCBC-826: Implement acouchbase for Windows.

  • PYCBC-622: Document/configure Git dependency.

  • PYCBC-673: Prefer locally bundled lcb include for installs.

  • PYCBC-681: Make OptionBlock arguments discoverable.

  • PYCBC-698: Fixed test failures against real servers.

  • PYCBC-711: Create AnalyticsIndexManager, fix analytics queries, with v3 tests.

  • PYCBC-719: The ViewIteratorTests all are skipping when they should not.

  • PYCBC-723: bucket.ping needs to be implemented.

  • PYCBC-732: QueryIndexManager interface work, plus fixes for failing tests.

  • PYCBC-746: Remove NodeManager from API.

  • PYCBC-747: Remove generic Manager API.

  • PYCBC-752: ViewIndexManager needs proper SDK3 interface.

  • PYCBC-754: Fix invalid named args in Collection.get.

  • PYCBC-771: Mark multi-operations as volatile until sdk-rfc done.

  • PYCBC-785: Expose ErrorContexts.

  • PYCBC-794: Implement Cluster.disconnect.

  • PYCBC-798: Ping is returning 'scope' instead of 'namespace'.

  • PYCBC-801: Reflect optional nature of parameters in OptionBlock constructors.

  • PYCBC-803: Reinstate non-hybrid (pure CMake) build.

  • PYCBC-815: Share lcb_INSTANCE objects between collections.

  • PYCBC-817: Collection get_and_touch, get_and_lock need to be SDK3-ized.

  • PYCBC-838: Client Durability support.

  • PYCBC-473: Add FTS Index Management.

  • PYCBC-691: Set up Combination Testing for SDK 3 - Server 5.5, 6.0, 6.5.

  • PYCBC-729: Add necessary build tools to the readme.md.

  • PYCBC-777: Complete KV doc for GA.

  • PYCBC-779: Getting Started docs Tidy Up.

  • PYCBC-781: Managing Connections doc.

  • PYCBC-841: Update integration testing Jenkins node labels.

  • PYCBC-844: Convert integration tests to nightlies.

  • PYCBC-743: Mark all ErrorContexts as Uncommitted.

  • PYCBC-751: AnalyticsIndexes manager missing on Cluster.

  • PYCBC-775: Migrate collection attributes to use timedelta for durations.

  • PYCBC-744: Ensure precedence between named param and option block is described.

  • PYCBC-864: Provide asyncio access to Cluster, also analytics and search.

  • PYCBC-707: Sweep through tests, examine why some are skipped.

  • PYCBC-840: Add testing for 6.5 with DP enabled.

  • PYCBC-845: Nightlies need to build and test (against mock) on more platforms.

  • PYCBC-847: Consolidate exceptions into one place.

  • PYCBC-870: Testing on MacOS.

  • PYCBC-873: CMake: Skip PythonLibs search for Hybrid builds, remove -pthreads.

  • PYCBC-886: Expiry not properly returned or set.

  • PYCBC-895: Improve navigability/API docs for async, remove factories.

  • PYCBC-896: Remove unused code (unshared collection, v2 async code).

Fixes

  • PYCBC-774: Proper implementation for Collection.get_all_replicas.

  • PYCBC-782: Fix durability_level on collection.remove.

  • PYCBC-789: N1QL query request to create index appears to fail.

  • PYCBC-792: Cluster.diagnostics always times out.

  • PYCBC-795: ViewManager needs to wrap http calls for proper exceptions.

  • PYCBC-799: Ensure v3 tests all pass on Jenkins against real servers.

  • PYCBC-800: Fix BucketMissingException when trying to connect to Cluster.

  • PYCBC-807: Correct CollectionManager docstrings.

  • PYCBC-808: Fix AnalyticsOptions code.

  • PYCBC-818: Collection.exists always returning true.

  • PYCBC-829: Collection.get_and_lock should not get and lock in 2 commands.

  • PYCBC-850: CBCollectionShared not passing through collection name.

  • PYCBC-855: ViewResult recurses infinitely on some platforms.

  • PYCBC-857: Address some missing error context types.

  • PYCBC-859: Bucket exception parsing broken by server message change.

  • PYCBC-756: Append, Prepend, Increment, Decrement need to move to BinaryCollection.

  • PYCBC-749: Remove additional overloads for query and search.

  • PYCBC-806: Various PEP8 formatting fixes.

  • PYCBC-809: PEP8/MyPy warning removal.

  • PYCBC-839: CreateCollection CollectionSpec must include MaxTTL.

  • PYCBC-760 Fixed Collection.exists implementation.

  • PYCBC-640 Implemented replica reads according to RFC.

  • PYCBC-768: Refactored durability params to prevent impossible combinations.

  • PYCBC-639: Example N1QL statements don’t seem to work in "Hello Couchbase" example.

  • PYCBC-667: Fixed Upsert Group fails with 'roles: value must be supplied'.

  • PYCBC-674: Fixed deprecation warnings from sdk2 when running sdk3.

  • PYCBC-675: Brough Result objects in line with RFC, removed unidiomatic interfaces.

  • PYCBC-694: Completed query implementation.

  • PYCBC-753: Collection APIs marked volatile.

  • PYCBC-763: Corrected MutateInResult.content_as implementation.

  • PYCBC-764: Delete or renamed remaining SDK2 references in main API: Renamed SDK2/sdk2 to Core/core where applicable. Removed classes & methods inapplicable to SDK3.

  • PYCBC-704: Implemented *CollectionOptions for Collection management API.

  • PYCBC-716: Tests should no longer try to do 6.5-specific tests against a 6.0 server.

  • PYCBC-686: Applied new naming convention for interfaces/protocols.

  • PYCBC-687: Support added for Python 3.8.

  • PYCBC-761: Added timeout to lookup_in operation.

  • PYCBC-784: Remove/move/mark "internal" Admin methods/class.

  • PYCBC-793: Cluster.bucket needs kwargs for the tests to work against the mock.

  • PYCBC-796: Move some tests on sdk2 to sdk3.

  • PYCBC-797: Bucket.ping needs to respect the timeout in the options if any.

  • PYCBC-824: QueryResult has a few fields that are not implemented yet.

  • PYCBC-831: Cluster settings like compression, tracing, etc.. should be set at Cluster initialisation only.

  • PYCBC-832: Test issues with cluster and opening new buckets.

  • PYCBC-835: Diagnostics hangs on any server < 6.5.

  • PYCBC-854: ping() needs to be at the cluster level as well.

  • PYCBC-860: Don’t pass a bucket name for cluster connections by default.

  • PYCBC-863: iterable_wrapper failing for some async operations.

  • PYCBC-869: Cattrs library doesn’t work with python 3.5.2.

  • PYCBC-874: Do cluster ops on 6.5-DP.

  • PYCBC-875: ViewQuery segfaults in bindings.

  • PYCBC-878: Tx stuff seems to have broken imports recently.

  • PYCBC-881: Make (txcouchbase|acouchbase).cluster.Cluster.connect return an instance of the relevant class.

  • PYCBC-882: Fix dropped imports.

  • PYCBC-883: Some remaining exceptions not listed in Error Handling RFC.

  • PYCBC-898: Correct threshold naming for search and query.

  • PYCBC-899: Import error in search tests.

  • PYCBC-902: Add more coverage to integration tests.

  • PYCBC-903: Further improve Async API/docstrings.

  • PYCBC-905: Pip install fails for latest sdk commits on python 3.5.x.

  • PYCBC-908: Add some missing View result types.

  • PYCBC-897: Update 'long_description' settings to conform with PyPi.

  • PYCBC-910: Factor CBCollectionShared into CBCollectionBase.

  • PYCBC-911: Remove content_as_array as not in RFC.

Pre-releases

Numerous Alpha and Beta releases were made in the run-up to the 3.0 release, and although unsupported, the release notes and download links are retained for archive purposes here.

Older Releases

Although no longer supported, documentation for older releases continues to be available in our docs archive.