Please also refer to the Server docs.
This section describes how to connect the Python SDK to a Couchbase cluster. It contains best practices as well as information on TLS/SSL and other advanced connection options.
A connection to a Couchbase Server cluster is represented by a
Cluster provides access to Buckets, Scopes, and Collections, as well as various Couchbase services and management interfaces.
The simplest way to create a
Cluster object is to call
Cluster.connect() with a connection string, username, and password:
cluster = Cluster.connect("couchbase://localhost", ClusterOptions(PasswordAuthenticator("username", "password"))) bucket = cluster.bucket("travel-sample") collection = bucket.default_collection() # You can access multiple buckets using the same Cluster object. another_bucket = cluster.bucket("beer-sample") # You can access collections other than the default # if your version of Couchbase Server supports this feature. customer_a = bucket.scope("customer-a") widgets = customer_a.collection("widgets")
If you are connecting to a version of Couchbase Server older than 6.5, it will be more efficient if the addresses are those of data (KV) nodes.
You will in any case, with 6.0 and earlier, need to open a
In a production environment, your connection string should include the addresses of multiple server nodes in case some are currently unavailable. Multiple addresses may be specified in a connection string by delimiting them with commas:
cluster = Cluster.connect("couchbase://node1.example.com,node2.example.com", ClusterOptions(PasswordAuthenticator("username", "password")))
|You don’t need to include the address of every node in the cluster. The client fetches the full address list from the first node it is able to contact.|
The backend implementation of connection strings parameters changed substantially in 4.0 and is not currently fully documented.
This will be resolved in a future 4.x release.
See more details on migrating to 4.0.
In any case, configuring client settings with
A Couchbase connection string is a comma-delimited list of IP addresses and/or hostnames, optionally followed by a list of parameters.
The parameter list is just like the query component of a URI; name-value pairs have an equals sign (
=) separating the name and value, with an ampersand (
&) between each pair.
Just as in a URI, the first parameter is prefixed by a question mark (
The full list of recognized parameters is documented in the client settings reference. Any client setting with a system property name may also be specified as a connection string parameter.
A connection string may optionally be prefixed by either
For more detailed documentation please refer to the libcouchbase connection string documentation.
Most of the high-level classes in the Python SDK are designed to be safe for concurrent use by multiple threads.
For asynchronous modes, you will get the best performance if you share and reuse instances of
Collection, all of which are thread-safe. For synchronous mode, it is better to use separate instances in different threads.
We recommend creating a single
Cluster instance when your application starts up, and sharing this instance throughout your application.
If you know at startup time which buckets, scopes, and collections your application will use, we recommend obtaining them from the
Cluster at startup time and sharing those instances throughout your application as well.
If your Couchbase Server cluster is running in a containerized, port mapped, or otherwise NAT’d environment like Docker or Kubernetes, a client running outside that environment may need additional information in order to connect the cluster. Both the client and server require special configuration in this case.
On the server side, each server node must be configured to advertise its external address as well as any custom port mapping.
This is done with the
setting-alternate-address CLI command introduced in Couchbase Server 6.5.
A node configured in this way will advertise two addresses: one for connecting from the same network, and another for connecting from an external network.
|Any TLS certificates must be set up at the point where the connections are being made.|
|If the client cannot load or was not built with OpenSSL, attempting an SSL connection will result in a 'FEATURE_UNAVAILABLE'.|
Couchbase Server Enterprise Edition and Couchbase Capella support full encryption of client-side traffic using Transport Layer Security (TLS). This includes key-value type operations, queries, and configuration communication. Make sure you have the Enterprise Edition of Couchbase Server, or a Couchbase Capella account, before proceeding with configuring encryption on the client side.
The Python SDK bundles Capella’s standard root certificate by default.
This means you don’t need any additional configuration to enable TLS — simply use
couchbases:// in your connection string.
|Capella’s root certificate is not signed by a well known CA (Certificate Authority). However, as the certificate is bundled with the SDK, it is trusted by default.|
As of SDK 4.1, if you connect to a Couchbase Server cluster with a root certificate issued by a trusted CA (Certificate Authority), you no longer need to configure the
cert_path property in the
The cluster’s root certificate just needs to be issued by a CA whose certificate is in your OpenSSL trust store. This can include publicly trusted CAs (e.g., GoDaddy, Verisign, etc…), plus any other CA certificates that you wish to add. The Python SDK uses Couchbase++ internally to retrieve the root CAs.
|Couchbase++ loads your platform’s root CA store using OpenSSL, therefore you should make sure that your system or platform is configured to support this.|
Depending on your OpenSSL installation, OpenSSL might not contain any certificates in its CA store by default, which you might wish to populate.
You can find Python’s OpenSSL defaults with the following command. Alternatively, you can configure the
SSL_CERT_FILE environment variable to set the directory or root CA store file Couchbase++ uses to retrieve root CAs.
python -c "import ssl; print(ssl.get_default_verify_paths())"
You can still provide a certificate explicitly if necessary:
Get the CA certificate from the cluster and save it in a text file.
Enable encryption on the client side and point it to the file containing the certificate.
It is important to make sure you are transferring the certificate in an encrypted manner from the server to the client side, so either copy it through SSH or through a similar secure mechanism.
If you are running on
localhost and just want to enable TLS for a development machine, just copying and pasting it suffices — so long as you use
127.0.0.1 rather than
localhost in the connection string.
This is because the certificate will not match the name localhost.
Navigate in the admin UI to
It looks similar to this:
-----BEGIN CERTIFICATE----- MIICmDCCAYKgAwIBAgIIE4FSjsc3nyIwCwYJKoZIhvcNAQEFMAwxCjAIBgNVBAMT ASowHhcNMTMwMTAxMDAwMDAwWhcNNDkxMjMxMjM1OTU5WjAMMQowCAYDVQQDEwEq MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzz2I3Gi1XcOCNRVYwY5R ................................................................ mgDnQI8nw2arBRoseLpF6WNw22CawxHVOlMceQaGOW9gqKNBN948EvJJ55Dhl7qG BQp8sR0J6BsSc86jItQtK9eQWRg62+/XsgVCmDjrB5owHPz+vZPYhsMWixVhLjPJ mkzeUUj/kschgQ0BWT+N+pyKAFFafjwFYtD0e5NwFUUBfsOyQtYV9xu3fw+T2N8S itfGtmmlEfaplVGzGPaG0Eyr53g5g2BgQbi5l5Tt2awqhd22WOVbCalABd9t2IoI F4+FjEqAEIr1mQepDaNM0gEfVcgd2SzGhC3yhYFBAH//8W4DUot5ciEhoBs= -----END CERTIFICATE-----
The next step is to enable encryption by connecting to a cluster with the 'couchbases://' protocol in the connection string and pass it the path to the certificate file via an Authenticator, or via '?cert_path=…' in the connection string itself.
cluster = Cluster("couchbases://localhost",ClusterOptions(PasswordAuthenticator("username","password",cert_path="/path/to/cluster.crt")))
Then use this custom
Cluster when opening the connection to the cluster.
If you want to verify it’s actually working, you can use a tool like
For example, an unencrypted upsert request looks like this (using
sudo tcpdump -i lo0 -A -s 0 port 11210):
After enabling encryption, you cannot inspect the traffic in cleartext (same upsert request, but watched on port 11207 which is the default encrypted port):
E.....@.@.............+....Z.'yZ..#........ ..... ...xuG.O=.#.........?.Q)8..D...S.W.4.-#....@7...^.Gk.4.t..C+......6..)}......N..m..o.3...d.,. ...W.....U.. .%v.....4....m*...A.2I.1.&.*,6+..#..#.5
For most use cases, connecting client software using a Couchbase SDK to the new Couchbase Capella service is similar to connecting to an on-premises Couchbase Cluster. The use of DNS-SRV. Alternate Address, and TLS is covered above.
We strongly recommend that the client and server are in the same LAN-like environment (e.g. AWS Availability Zone). As this may not always be possible during development, read the guidance on working with constrained network environments. More details on connecting your client code to Couchbase Capella can be found in the Cloud docs.
Some DNS caching providers (notably, home routers) can’t handle an SRV record that’s large — if you have DNS-SRV issues with such a set-up, reduce your DNS-SRV to only include three records. [For development only, not production.]. Our Troubleshooting Cloud Connections page will help you to diagnose this and other problems — as well as introducing the SDK doctor tool.
The Couchbase Python SDK provides first-class support for asynchronous programming. The supported asynchronous APIs offer a similar API to the synchronous API.
Methods in the asynchronous API return instances of the relevant Async API:
Futurefor asyncio (
acouchbase.cluster.Clustersupplies the relevant Cluster object)
Reference our asynchronous programming page for more details.