Install and Start Using the Python SDK with Couchbase Server

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.

Hello Couchbase

On this page we show you how to quickly get up and running — installing the Couchbase Python SDK, and trying out the Hello World code example against Couchbase Capella, or against a local Couchbase cluster.

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.0 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 = "Password123!"
bucket_name = "travel-sample"
# User Input ends here.

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

# Connect options - global timeout opts
timeout_opts = ClusterTimeoutOptions(kv_timeout=timedelta(seconds=10))

# get a reference to our cluster
cluster = Cluster('couchbases://{}'.format(endpoint),
                  ClusterOptions(auth, timeout_options=timeout_opts))

# 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:
        sql_query = 'SELECT VALUE name FROM `travel-sample`.inventory.airline WHERE 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)


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 = "username"
password = "password"
bucket_name = "travel-sample"
cert_path = "path/to/certificate"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(
    username,
    password,
    # NOTE: If using SSL/TLS, add the certificate path.
    # We strongly reccomend this for production use.
    # cert_path=cert_path
)

# Get a reference to our cluster
# NOTE: For TLS/SSL connection use 'couchbases://<your-ip-address>' instead
cluster = Cluster('couchbase://localhost', 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:
        sql_query = 'SELECT VALUE name FROM `travel-sample`.inventory.airline WHERE 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)


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 trial version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

Quick Installation

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

macOS 11 & 12
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.

As of the 4.0.1 release of the Python SDK, wheels are available for Python 3.7 - 3.10.

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

$ brew update

Install a compatible Python 3:

$ brew install openssl@1.1 python3

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

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

Now, install the Python SDK:

$ sudo -H python3 -m pip install couchbase

Note, check that you have a supported version of Python (3.7 - 3.10). 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.

As of the 4.0.2 release of the Python SDK, manylinux wheels are available for Python 3.7 - 3.10.

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 (3.7 - 3.10). 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.

As of the 4.0.2 release of the Python SDK, manylinux wheels are available for Python 3.7 - 3.10.

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.

Wheels are available on Windows for Python 3.7 - 3.10.

python -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 OpenSSL.

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.

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:

Connect to a cluster, bucket, and collection;
Add and retrieve a new document;
Look up (SQL-type query) the new document by attribute value.

Prerequisites

Here are all of 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)

Connection

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

Couchbase Capella requires mandatory use of TLS (Transport Layer Security). As of Python SDK version 4.0, the standard certificate required to connect to a Capella cluster is automatically included with no additional configuration.

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

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

# Connect options - global timeout opts
timeout_opts = ClusterTimeoutOptions(kv_timeout=timedelta(seconds=10))

# get a reference to our cluster
cluster = Cluster('couchbases://{}'.format(endpoint),
                  ClusterOptions(auth, timeout_options=timeout_opts))

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

Couchbase Capella uses Roles to control user access to database resources. For the purposes of this example, we can use the Organization Owner role automatically assigned to a user account during installation of the Capella cluster. This role grants full access to a Capella organization, including full data access to all projects and clusters. In a production scenario, we strongly recommend setting up users with more granular access roles as a best practice.

For the SDK client to access cluster data, you will need to set up credentials for your database by following these steps.

# Update this to your cluster
username = "username"
password = "password"
bucket_name = "travel-sample"
cert_path = "path/to/certificate"
# User Input ends here.

# Connect options - authentication
auth = PasswordAuthenticator(
    username,
    password,
    # NOTE: If using SSL/TLS, add the certificate path.
    # We strongly reccomend this for production use.
    # cert_path=cert_path
)

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

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

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 Manage Users, Groups, and Roles page. 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(bucket_name)

We are working with the travel-sample data bucket. If you are not, update the bucket_name variable used in the example with your bucket name.

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 will use the airline collection within the inventory scope from travel-sample bucket as an example.

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

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

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 SQL++ (formerly N1QL) queries are performed by invoking the Cluster.query() method. The following function executes a lookup for airline documents 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`.inventory.airline WHERE 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

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