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 withtwisted andasyncio.
In this guide, you will learn:
How toadd and retrieve Documents.
How tolookup documents with theSQL++ (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 toCouchbase 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 connectionfrom couchbase.auth import PasswordAuthenticatorfrom couchbase.cluster import Cluster# needed for options -- cluster, timeout, SQL++ (N1QL) query, etc.from couchbase.options import (ClusterOptions, ClusterTimeoutOptions, QueryOptions)# Update this to your clusterendpoint = "--your-instance--.dp.cloud.couchbase.com"username = "username"password = "Password!123"bucket_name = "travel-sample"# User Input ends here.# Connect options - authenticationauth = PasswordAuthenticator(username, password)# get a reference to our clusteroptions = 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 bucketcb = 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 functiondef 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 callsigndef 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 connectionfrom couchbase.auth import PasswordAuthenticatorfrom couchbase.cluster import Cluster# needed for options -- cluster, timeout, SQL++ (N1QL) query, etc.from couchbase.options import (ClusterOptions, ClusterTimeoutOptions, QueryOptions)# Update this to your clusterusername = "Administrator"password = "password"bucket_name = "travel-sample"# User Input ends here.# Connect options - authenticationauth = PasswordAuthenticator( username, password,)# Get a reference to our cluster# NOTE: For TLS/SSL connection use 'couchbases://<your-ip-address>' insteadcluster = 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 bucketcb = cluster.bucket(bucket_name)cb_coll = cb.scope("inventory").collection("airline")# Get a reference to the default collection, required for older Couchbase server versionscb_coll_default = cb.default_collection()# upsert document functiondef 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 functiondef 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 callsigndef 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 Bucketusing either theWeb interfaceor thecommand line.
TheCouchbase Capella free tier version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.
Quick Installation
The SDK will run onsupported versions Python.A more detailed guide in ourInstallation page covers every supported platform,but this section should be enough to get up and running formostsupported 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 ourfull installation guide.Otherwise, read on for a quick install on macOSBig Sur orMonterey.
The Python SDK has wheels are available on macOS forsupported versions of Python.
First, make sure that yourbrew package index is up-to-date:
$ brew update
Install a compatible Python 3:
$ brew install python3
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
Starting with Python 3.11.5, macOS installers from python.org now useOpenSSL 3.0. If using a version prior to 4.1.9 of the Python SDK, a potential side-effect of this change is anImportError: 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 thePYCBC_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. |
Note, check that you have asupported version of Python.Suggestions for platforms with an outdated build chain, such as CentOS 7, can be found in ourInstallation Guide.Assuming you have an updated build environment, follow these steps.
The Python SDK has manylinux wheels available forsupported versions of Python.
During first-time setup, install the prerequisites:
$ sudo yum install gcc gcc-c++ git python3-devel python3-pip
Full details of prerequisites can be foundhere.
Now you can install the latest Python SDK (for older versions, see theRelease Notes page):
$ python3 -m pip install couchbase
Note, check that you have asupported version of Python.Suggestions for platforms with an outdated build chain, such as Debian 9, can be found in ourInstallation Guide.Assuming you have an updated build environment, follow these steps.
The Python SDK has manylinux wheels available forsupported versions of Python.
During first-time setup, install the prerequisites:
$ sudo apt-get install git python3-dev python3-pip python3-setuptools build-essential
Full details of prerequisites can be foundhere.
Now you can install the latest Python SDK (for older versions, see theRelease Notes page):
$ python3 -m pip install couchbase
Download and install Python frompython.org.Best practice is to use a Python virtual environment such asvenv orpyenv.
Checkout thepyenv-win project to manage multiple versions of Python. |
The Python SDK has wheels available on Windows forsupported versions of Python.
python -m pip install couchbase
Starting with Python 3.11.5, Windows builds from python.org now useOpenSSL 3.0. If using a version prior to 4.1.9 of the Python SDK, a potential side-effect of this change is anImportError: 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 thePYCBC_OPENSSL_DIR environment variable to the path where the OpenSSL 1.1 libraries (libssl-1_1.dll andlibcrypto-1_1.dll ) can be found. |
The standard Python distributions for Windows include OpenSSL DLLs, as PIP and the inbuiltssl
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 thebuild instructions on the GitHub repo. |
If there are any problems, refer to the fullInstallation page.
Prerequisites
The following code samples assume:
Couchbase Capella
Local Couchbase Server
You have signed up toCouchbase 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 theCapella connection page for more details.
Couchbase Capella usesRoles to control user access to cluster resources.For the purposes of this guide, you can use theOrganization 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 theWeb interface.
A user is created with permissions to access your cluster (at least Application Access permissions).SeeManage Users, Groups and Roles for more details.
Couchbase Server usesRole Based Access Control (RBAC) to control access to resources.In this guide we suggest using theFull 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 namedcb-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 connectionfrom couchbase.auth import PasswordAuthenticatorfrom 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 theManaging 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 usingcouchbases://
in the connection string as in this example.
# Update this to your clusterendpoint = "--your-instance--.dp.cloud.couchbase.com"username = "username"password = "Password!123"bucket_name = "travel-sample"# User Input ends here.# Connect options - authenticationauth = PasswordAuthenticator(username, password)# get a reference to our clusteroptions = 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 awan_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 seeConstrained Network Environments.
The Configuration Profiles feature is currently aVolatile API and may be subject to change. |
# Update this to your clusterusername = "Administrator"password = "password"bucket_name = "travel-sample"# User Input ends here.# Connect options - authenticationauth = PasswordAuthenticator( username, password,)# Get a reference to our cluster# NOTE: For TLS/SSL connection use 'couchbases://<your-ip-address>' insteadcluster = 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 becouchbase://localhost
.For production deployments, you will want to use a secure server, withcouchbases://
.
Following successful authentication, add this code snippet to access yourBucket
:
# get a reference to our bucketcb = cluster.bucket(bucket_name)
Add and Retrieve Documents
The Python SDK supports full integration with theCollections feature introduced in Couchbase Server 7.0.Collections allow documents to be grouped by purpose or theme, according to a specifiedScope.
Here we refer to theusers
collection within thetenant_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
|
Let’s create a dictionary object in our application that we can add to ourtravel-sample
bucket that conforms to the structure of a document of typeairline
.
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 theCollection
class such asCollection.get
andCollection.upsert
.Simply pass the key (and value, if applicable) to the relevant methods.
The following function willupsert a document and print the returnedCAS 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 theupsert_document()
function passing in ourairline
document:
upsert_document(airline)
Now let’s retrieve that document using a key-value operation.The following function runs aget()
for a document key and either logs out the result or error in our console:
# get document functiondef 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 theget_airline_by_key
function passing in our valid document keyairline_8091
:
get_airline_by_key("airline_8091")
SQL++ Lookup
Couchbase SQL++ queries can be performed at theCluster
orScope
level by invokingCluster.query()
orScope.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 isairline
:
# query for new document by callsigndef 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 thelookup_by_callsign
function passing in our callsignCBS
:
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:1598469741559152640Get 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:
OurTravel Sample Application demonstrates all the basics you need to know;
ExploreKey Value Operations (CRUD) against a document database;
OrQuery with our SQL-based SQL++ query language;
Or read up onwhich service fits your use case.
Additional Resources
The API reference is generated for each release and the latest can be foundhere.
Older API references are linked from their respective sections in theIndividual Release Notes.Most of the API documentation can also be accessed viapydoc
.
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 onGitHub.
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 onConstrained Network Environments.
If you have a consumer-grade router which has problems with DNS-SRV records review ourTroubleshooting Guide.
Ourcommunity forum is a great source of help.