Install and Start Using the Python SDK with Couchbase Server

    +
    The Couchbase Python SDK allows Python applications to access a Couchbase cluster. The Python SDK offers a traditional synchronous API as well as integration with twisted, gevent, and asyncio. It depends on the C SDK, libcouchbase, (included automatically) which it uses for performance and reliability.

    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.

    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.
    $ brew update # get list of latest packages
    $ brew install python3
    $ brew install openssl # for TLS/SSL support - optional
    $ 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.

    Hello Couchbase

    At this point we want to transition from the terminal to your code editor of choice.

    Let’s now create an empty file named cb-test.py and walk through adding code step-by-step:

    • Connect to a cluster, bucket, and default collection;

    • Add and retrieve a new document;

    • Look up (SQL-type query) the new document by attribute value.

    Connection

    The basic imports and connection string that you’ll need are given below — for more background information, refer to the Managing Connections page.

    # needed for any cluster connection
    from couchbase.cluster import Cluster, ClusterOptions
    from couchbase_core.cluster import PasswordAuthenticator
    
    # needed to support SQL++ (N1QL) query
    from couchbase.cluster import QueryOptions
    
    # get a reference to our cluster
    cluster = Cluster('couchbase://localhost', ClusterOptions(
      PasswordAuthenticator('Administrator', 'password')))

    Couchbase uses Role Based Access Control (RBAC) to control access to resources. For the sake of this example, we are connecting to Couchbase using the Full Admin role created during the installation of our Couchbase Server. The connection is being made to a single Couchbase node running on a host named hulk.

    Couchbase RBAC is fully described in the section Authorization. An authenticator, containing username and password, should be defined, and then passed to the cluster. Following successful authentication, the bucket can be opened:

    # get a reference to our bucket
    cb = cluster.bucket('travel-sample')
    We are working with the travel-sample data bucket. If you are not, substitute travel-sample with your bucket-name.

    If you are connecting to Couchbase Cloud rather than a local Couchbase Server, then also refer to the Cloud section, below.

    See Managing Connections for more connection options and details about the connection string.

    # get a reference to the default collection
    cb_coll = cb.default_collection()

    The latest Couchbase Server release (6.5), brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to a specified Collection. For our "Hello Couchbase" example we will simply use DefaultCollection, rather than a specific collection, but once the feature is generally available the best practice will be to group documents into collections by type.

    Document Addition and Retrieval

    Let’s create a dictionary object in our application that we can add to our travel-sample bucket that conforms to the structure of a document of type airline.

    airline = {
      "type": "airline",
      "id": 8091,
      "callsign": "CBS",
      "iata": None,
      "icao": None,
      "name": "Couchbase Airways",
    }

    Document operations, such as storing and retrieving documents, can be done using simple methods on the Bucket class such as Bucket.get and Bucket.upsert. Simply pass the key (and value, if applicable) to the relevant methods.

    The following function will upsert() a document and print the returned CAS value:

    def upsert_document(doc):
      print("\nUpsert CAS: ")
      try:
        # key will equal: "airline_8091"
        key = doc["type"] + "_" + str(doc["id"])
        result = cb_coll.upsert(key, doc)
        print(result.cas)
      except Exception as e:
        print(e)

    Now, we can simply call the upsert_document function passing in our airline document:

    upsert_document(airline)

    Now let’s retrieve that document using a key-value operation. The following function runs a get() for a document key and either logs out the result or error in our console:

    # get document function
    def get_airline_by_key(key):
      print("\nGet Result: ")
      try:
        result = cb_coll.get(key)
        print(result.content_as[str])
      except Exception as e:
        print(e)

    Key-value Operations are described in detail on the KV Operations page.

    Now, we can simply call the get_airline_by_key function passing in our valid document key airline_8091:

    get_airline_by_key("airline_8091")

    SQL++ Lookup

    Couchbase N1QL queries are performed by invoking the Cluster.query() method. The following function executes a lookup for documents of type='airline' by a provided callsign:

    # query for new document by callsign
    def lookup_by_callsign(cs):
      print("\nLookup Result: ")
      try:
        sql_query = 'SELECT VALUE name FROM `travel-sample` WHERE type = "airline" AND callsign = $1'
        row_iter = cluster.query(
          sql_query,
          QueryOptions(positional_parameters=[cs]))
        for row in row_iter: print(row)
      except Exception as e:
        print(e)

    We call the lookup_by_callsign function passing in our callsign CBS:

    lookup_by_callsign("CBS")

    Execute!

    Now we can run our code using the following command:

    $ python3 cb-test.py

    The results you should expect are as follows:

    Upsert CAS:
    1598469741559152640
    
    Get Result:
    {'type': 'airline', 'id': 8091, 'callsign': 'CBS', 'iata': None, 'icao': None, 'name': 'Couchbase Airways'}
    
    Lookup Result:
    Couchbase Airways

    Cloud Connections

    For developing on Couchbase Cloud, try the Cloud-based Hello World program.

    If you are not working from the same Availability Zone as your Couchbase Cloud, refer to the following:

    Additional Resources

    The API reference is generated for each release and the latest can be found here.

    Older API references are linked from their respective sections in the Individual Release Notes. Most of the API documentation can also be accessed via pydoc.

    The Migrating from SDK2 to 3 page highlights the main differences to be aware of when migrating your code.

    Couchbase welcomes community contributions to the Python SDK. The Python SDK source code is available on GitHub.

    PyPy support

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

    Please create a Jira ticket if you require a PyPy-compatible version of the SDK.