Start Using the Python SDK

tutorial

Get up and running quickly, installing the Couchbase Python SDK, and running our Hello World example.

The Couchbase Python SDK allows Python applications to access a Couchbase cluster. It offers a traditional synchronous API as well as integration with twisted and asyncio.

In this guide, you will learn:

How to connect to Couchbase Capella or Couchbase Server.
How to add and retrieve Documents.
How to lookup documents with the SQL++ (formerly N1QL) query language.

Hello Couchbase

We will go through the code sample step by step, but for those in a hurry to see it, here it is:

Couchbase Capella Sample
Local Couchbase Server

To connect to Couchbase Capella, be sure to get the correct endpoint as well as user, password, and bucket name. The certificate for connecting to Capella is included in the 4.1 Python SDK.

from datetime import timedelta

# needed for any cluster connection
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
# needed for options -- cluster, timeout, SQL++ (N1QL) query, etc.
from couchbase.options import (ClusterOptions, ClusterTimeoutOptions,
                               QueryOptions)


# Update this to your cluster
endpoint = "--your-instance--.dp.cloud.couchbase.com"
username = "username"
password = "Password!123"
bucket_name = "travel-sample"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(username, password)

# get a reference to our cluster
options = ClusterOptions(auth)
# Sets a pre-configured profile called "wan_development" to help avoid latency issues
# when accessing Capella from a different Wide Area Network
# or Availability Zone(e.g. your laptop).
options.apply_profile('wan_development')
cluster = Cluster('couchbases://{}'.format(endpoint), options)

# Wait until the cluster is ready for use.
cluster.wait_until_ready(timedelta(seconds=5))

# get a reference to our bucket
cb = cluster.bucket(bucket_name)

cb_coll = cb.scope("inventory").collection("airline")



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)

# 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)

# query for new document by callsign


def lookup_by_callsign(cs):
    print("\nLookup Result: ")
    try:
        inventory_scope = cb.scope('inventory')
        sql_query = 'SELECT VALUE name FROM airline WHERE callsign = $1'
        row_iter = inventory_scope.query(
            sql_query,
            QueryOptions(positional_parameters=[cs]))
        for row in row_iter:
            print(row)
    except Exception as e:
        print(e)


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

upsert_document(airline)

get_airline_by_key("airline_8091")

lookup_by_callsign("CBS")

from datetime import timedelta

# needed for any cluster connection
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
# needed for options -- cluster, timeout, SQL++ (N1QL) query, etc.
from couchbase.options import (ClusterOptions, ClusterTimeoutOptions,
                               QueryOptions)

# Update this to your cluster
username = "Administrator"
password = "password"
bucket_name = "travel-sample"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(
    username,
    password,
)

# Get a reference to our cluster
# NOTE: For TLS/SSL connection use 'couchbases://<your-ip-address>' instead
cluster = Cluster('couchbase://your-ip', ClusterOptions(auth))

# Wait until the cluster is ready for use.
cluster.wait_until_ready(timedelta(seconds=5))

# get a reference to our bucket
cb = cluster.bucket(bucket_name)

cb_coll = cb.scope("inventory").collection("airline")

# Get a reference to the default collection, required for older Couchbase server versions
cb_coll_default = cb.default_collection()

# upsert document function


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)

# 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)

# query for new document by callsign


def lookup_by_callsign(cs):
    print("\nLookup Result: ")
    try:
        inventory_scope = cb.scope('inventory')
        sql_query = 'SELECT VALUE name FROM airline WHERE callsign = $1'
        row_iter = inventory_scope.query(
            sql_query,
            QueryOptions(positional_parameters=[cs]))
        for row in row_iter:
            print(row)
    except Exception as e:
        print(e)


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

upsert_document(airline)

get_airline_by_key("airline_8091")

lookup_by_callsign("CBS")

As well as the Python SDK (see below), 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.

The Couchbase Capella free tier version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

Quick Installation

The SDK will run on supported versions Python. A more detailed guide in our Installation page covers every supported platform, but this section should be enough to get up and running for most supported Operating Systems.

macOS 12 & 13
Red Hat & CentOS
Debian & Ubuntu
Windows

If you are running Catalina (macOS 10.15) — or have other detailed requirements — take a look at our full installation guide. Otherwise, read on for a quick install on macOS Big Sur or Monterey.

The Python SDK has wheels are available on macOS for supported versions of Python.

First, make sure that your brew package index is up-to-date:

$ brew update

Install a compatible Python 3 — OpenSSL not needed from SDK version 4.1.9:

$ brew install openssl@1.1 python3

Starting with Python 3.11.5, macOS installers from python.org now use OpenSSL 3.0. If using a version prior to 4.1.9 of the Python SDK, a potential side-effect of this change is an ImportError: DLL load failed while importing pycbc_core error. Upgrade the SDK to a version >= 4.1.9 to avoid this side-effect. If unable to upgrade, a work-around is to set the PYCBC_OPENSSL_DIR environment variable to the path where the OpenSSL 1.1 libraries (libssl.1.1.dylib ` and `libcrypto.1.1.dylib) can be found.

Ensure that the Python installation can be called from the shell:

$ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.zshrc

$ source ~/.zshrc

Now, install the Python SDK:

$ sudo -H python3 -m pip install couchbase

Note, check that you have a supported version of Python. Suggestions for platforms with an outdated build chain, such as CentOS 7, can be found in our Installation Guide. Assuming you have an updated build environment, follow these steps.

The Python SDK has manylinux wheels available for supported versions of Python.

During first-time setup, install the prerequisites:

$ sudo yum install gcc gcc-c++ git python3-devel python3-pip openssl-devel

Full details of prerequisites can be found here.

Now you can install the latest Python SDK (for older versions, see the Release Notes page):

$ python3 -m pip install couchbase

Note, check that you have a supported version of Python. Suggestions for platforms with an outdated build chain, such as Debian 9, can be found in our Installation Guide. Assuming you have an updated build environment, follow these steps.

The Python SDK has manylinux wheels available for supported versions of Python.

During first-time setup, install the prerequisites:

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

Full details of prerequisites can be found here.

Now you can install the latest Python SDK (for older versions, see the Release Notes page):

$ python3 -m pip install couchbase

Download and install Python from python.org. Best practice is to use a Python virtual environment such as venv or pyenv.

Checkout the pyenv-win project to manage multiple versions of Python.

The Python SDK has wheels available on Windows for supported versions of Python.

python -m pip install couchbase

Starting with Python 3.11.5, Windows builds from python.org now use OpenSSL 3.0. If using a version prior to 4.1.9 of the Python SDK, a potential side-effect of this change is an ImportError: DLL load failed while importing pycbc_core error. Upgrade the SDK to a version >= 4.1.9 to avoid this side-effect. If unable to upgrade, a work-around is to set the PYCBC_OPENSSL_DIR environment variable to the path where the OpenSSL 1.1 libraries (libssl-1_1.dll and libcrypto-1_1.dll) can be found.

The standard Python distributions for Windows include OpenSSL DLLs, as PIP and the inbuilt ssl module require it for correct operation. Prior to version 4.1.9 of the Python SDK, the binary wheels for Windows are built against OpenSSL 1.1. Version 4.1.9 and beyond statically link against BoringSSL thus removing the OpenSSL requirement.

If you require a version that doesn’t have a suitable binary wheel on PyPI, follow the build instructions on the GitHub repo.

If there are any problems, refer to the full Installation page.

Prerequisites

The following code samples assume:

Couchbase Capella
Local Couchbase Server

You have signed up to Couchbase Capella.
You have created your own bucket, or loaded the Travel Sample dataset. Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster.
A user is created with permissions to access the cluster (at least Application Access permissions). See the Capella connection page for more details.

Couchbase Capella uses Roles to control user access to database resources. For the purposes of this guide, you can use the Organization Owner role automatically assigned to your account during installation of the Capella cluster. In a production scenario, we strongly recommend setting up users with more granular access roles as a best practice.

Couchbase Server is installed and accessible locally.
You have created your own bucket, or loaded the Travel Sample dataset using the Web interface.
A user is created with permissions to access your cluster (at least Application Access permissions). See Manage Users, Groups and Roles for more details.

Couchbase Server uses Role Based Access Control (RBAC) to control access to resources. In this guide we suggest using the Full Admin role created during setup of your local Couchbase Server cluster. For production client code, you will want to use more appropriate, restrictive settings.

Step-by-Step

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.

Here are all the import statements that you will need to run the sample code:

from datetime import timedelta

# needed for any cluster connection
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
# needed for options -- cluster, timeout, SQL++ (N1QL) query, etc.
from couchbase.options import (ClusterOptions, ClusterTimeoutOptions,
                               QueryOptions)

Connect

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

Couchbase Capella
Local Couchbase Server

From version 4.0, the Python SDK includes Capella’s standard certificates by default, so you don’t need any additional configuration. You do need to enable TLS, which can be done by simply using couchbases:// in the connection string as in this example.

# Update this to your cluster
endpoint = "--your-instance--.dp.cloud.couchbase.com"
username = "username"
password = "Password!123"
bucket_name = "travel-sample"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(username, password)

# get a reference to our cluster
options = ClusterOptions(auth)
# Sets a pre-configured profile called "wan_development" to help avoid latency issues
# when accessing Capella from a different Wide Area Network
# or Availability Zone(e.g. your laptop).
options.apply_profile('wan_development')
cluster = Cluster('couchbases://{}'.format(endpoint), options)

# Wait until the cluster is ready for use.
cluster.wait_until_ready(timedelta(seconds=5))

When accessing Capella from a different Wide Area Network or Availability Zone, you may experience latency issues with the default connection settings. SDK 4.1 introduces a wan_development Configuration Profile, which provides pre-configured timeout settings suitable for working in high latency environments. Basic usage is shown in the example above, but if you want to learn more see Constrained Network Environments.

The Configuration Profiles feature is currently a Volatile API and may be subject to change.

# Update this to your cluster
username = "Administrator"
password = "password"
bucket_name = "travel-sample"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(
    username,
    password,
)

# Get a reference to our cluster
# NOTE: For TLS/SSL connection use 'couchbases://<your-ip-address>' instead
cluster = Cluster('couchbase://your-ip', ClusterOptions(auth))

# Wait until the cluster is ready for use.
cluster.wait_until_ready(timedelta(seconds=5))

For developing locally on the same machine as Couchbase Server, your URI can be couchbase://localhost. For production deployments, you will want to use a secure server, with couchbases://.

Following successful authentication, add this code snippet to access your Bucket:

# get a reference to our bucket
cb = cluster.bucket(bucket_name)

Add and Retrieve Documents

The Python SDK supports full integration with the Collections feature introduced in Couchbase Server 7.0. Collections allow documents to be grouped by purpose or theme, according to a specified Scope.

Here we refer to the users collection within the tenant_agent_00 scope from the Travel Sample bucket as an example, but you may replace this with your own data.

cb_coll = cb.scope("inventory").collection("airline")

The code shows how you would use a named collection and scope.

For Local Couchbase Server only

The default_collection must be used when connecting to a 6.6 cluster or earlier.

# Get a reference to the default collection, required for older Couchbase server versions
cb_coll_default = cb.default_collection()

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",
}

Data operations, such as storing and retrieving documents, can be done using simple methods on the Collection class such as Collection.get and Collection.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)

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)

Call the get_airline_by_key function passing in our valid document key airline_8091:

get_airline_by_key("airline_8091")

SQL++ Lookup

Couchbase SQL++ queries can be performed at the Cluster or Scope level by invoking Cluster.query() or Scope.query().

Cluster level queries require you to specify the fully qualified keyspace each time (e.g. travel-sample.inventory.airline). However, with a Scope level query you only need to specify the Collection name — which in this case is airline:

# query for new document by callsign


def lookup_by_callsign(cs):
    print("\nLookup Result: ")
    try:
        inventory_scope = cb.scope('inventory')
        sql_query = 'SELECT VALUE name FROM airline WHERE callsign = $1'
        row_iter = inventory_scope.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

Next Steps

Now you’re up and running, try one of the following:

Our Travel Sample Application demonstrates all the basics you need to know;
Explore Key Value Operations (CRUD) against a document database;
Or Query with our SQL-based SQL++ query language;
Or read up on which service fits your use case.

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.

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

Troubleshooting

Couchbase Server is designed to work in the same WAN or availability zone as the client application. If you’re running the SDK on your laptop against a Capella cluster, see further information on:
- 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.
Our community forum is a great source of help.