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.

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.

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.

Prerequisites

As well as the Python SDK (see above), and a running instance of Couchbase Server, you will need to load up the Travel Sample Bucket using either the Web interface or the command line.

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 locally.

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, which includes all documents in a bucket, and is forwards and backwards compatible with all supported versions of Couchbase Server. Once the Collection 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:

Notes on Constrained Network Environments.
Network Requirements.
If you have a consumer-grade router which has problems with DNS-SRV records review our Troubleshooting Guide.

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.