Using the Python SDK
The Couchbase Python SDK library allows you to connect to a Couchbase cluster from Python. The Python SDK uses the high-performance C++ library, Couchbase++, to handle communicating to the cluster over the Couchbase binary protocol.
Useful Links
How to Engage
- Join Discord and contribute.
The Couchbase Discord server is a place where you can collaborate about all things Couchbase. Connect with others from the community, learn tips and tricks, and ask questions.
Ask and/or answer questions on the Python SDK Forums.
Installing the SDK
Note
Best practice is to use a Python virtual environment such as venv or pyenv. Checkout:
Note
Wheels are currently only available on Windows for Python 3.7 - 3.10. We will endeavor to add more in the near future.
Prereqs
If not on platform that has a binary wheel availble, the following is needed:
A C++ compiler supporting C++ 17
cmake (version >= 3.17)
Git
OpenSSL
After the above have been installed, pip install setuptools and wheel (see command below).
$ python3 -m pip install --upgrade pip setuptools wheel
Install
$ python3 -m pip install couchbase
Introduction
Connecting to a Couchbase cluster is as simple as creating a new Cluster instance to represent the Cluster
you are using, and then using the bucket and collection commands against this to open a connection to open
your specific bucket and collection. You are able to execute most operations immediately, and they will be
queued until the connection is successfully established.
Here is a simple example of creating a Cluster instance, retrieving a document and using SQL++ (a.k.a. N1QL).
# needed for any cluster connection
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
# options for a cluster and SQL++ (N1QL) queries
from couchbase.options import ClusterOptions, QueryOptions
# get a reference to our cluster
auth = PasswordAuthenticator('username', 'password')
cluster = Cluster.connect('couchbase://localhost', ClusterOptions(auth))
# get a reference to our bucket
cb = cluster.bucket('travel-sample')
# get a reference to the default collection
cb_coll = cb.default_collection()
# get a document
result = cb_coll.get('airline_10')
print(f'Document content: {result.content_as[dict]}')
# using SQL++ (a.k.a N1QL)
call_sign = 'CBS'
sql_query = 'SELECT VALUE name FROM `travel-sample` WHERE type = "airline" AND callsign = $1'
query_res = cluster.query(sql_query, QueryOptions(positional_parameters=[call_sign]))
for row in query_res:
print(f'Found row: {row}')
Source Control
The source control is available on Github. Once you have cloned the repository, you may contribute changes through our gerrit server. For more details see CONTRIBUTING.md.