A newer version of this documentation is available.

View Latest

Managing Connections Using the Python SDK with Couchbase Server

    This section describes how to connect the Python SDK to a Couchbase cluster and bucket. It contains best practices as well as information on the connection string, SSL and other advanced connection options.

    You can specify additional options when connecting to the cluster by using the connection string. It indicates to the client where cluster nodes may be found and how to connect to them. Note that it is common to other Couchbase SDKs as well as the command-line client. The connection string uses a URI-like format familiar to what is used in other database systems.

    Any Cluster nodes addresses passed in to establish (bootstrap) the connection should be for data (KV) nodes.

    Connecting to a Bucket

    All Couchbase Server-resources are protected by Role-Based Access Control (RBAC). Therefore, to connect to a bucket, you must pass appropriate credentials: these consist of a username and password that correspond to a user currently defined on Couchbase Server. This user-definition is associated with one or more roles, each of which in turn corresponds to a set of privileges. When authentication occurs, Couchbase Server checks to ensure that the authenticated user’s privileges do permit access to the requested resource: if they do not, access is denied.

    The following code demonstrates how authentication can be managed:

    from couchbase.cluster import Cluster
    from couchbase.cluster import PasswordAuthenticator
    cluster = Cluster('couchbase://localhost')
    authenticator = PasswordAuthenticator('username', 'password')
    cb = cluster.open_bucket('bucket-name')

    For more information on authentication and RBAC, see Authentication.

    Note that a bucket-connection closes once it falls out of scope and has no other objects referencing it. It is advised to create only a single bucket object per application (or thread) for each Couchbase bucket your application connects to.

    Disconnecting from a Bucket

    A Bucket object will disconnect from the cluster when it falls out of scope; that is, when it is no longer being referenced by anything in your Python application. You can still close a bucket manually via the synchronous API using the Bucket._close() method. This method should only be used as a last resort, as it may cause unexpected behavior if there are pending operations on the object.

    Scalability and concurrency

    Creating a new Bucket object is relatively expensive, and keeping many idle Bucket objects will negatively impact server performance (if done at a large scale).

    If using an asynchronous framework (such as Gevent or Twisted), your application will require only one Bucket instance per Couchbase bucket. Likewise, if your Python application only contains a single thread then you need establish only a single Bucket object per Couchbase bucket.

    If using multiple Python threads, it may be possible to share a single Bucket object across multiple threads (using locking). The exact number of Bucket objects to be created will depend on the activity pattern of the application. It is recommended to start off and develop with a single object for all threads. If you realize that your application is suffering in performance because of threads waiting for the Bucket object’s lock, you may implement a form of pooling or sharing so that n number of buckets be available.

    If using multiple processes (such as with the multiprocessing module), or using a Python module which creates multiple processes, ensure that the Bucket object is not created in the parent process! Your Python interpreter may crash if the same Bucket object exists in more than a single process.

    Connection Limits

    Each Couchbase Data node allows by default, in Couchbase Data Platform 6.0 and earlier, up to 30,000 concurrent key-value connections per port exposed to the user by the Data Service (ports 11210 and 11207). This means that if you are mixing SSL connections (port 11207) and plain connections (port 11210), you can have 30,000 connections on each of these two ports, or up to 60,000 in total. If you are using plain (or SSL) alone, then the limit is 30,000.

    From 6.5 onwards, the default value is 65,000 connections to the server — with 5000 of these reserved for system use. Thus, you can use 60,000 connections even if you only use_ one_ of the two ports (plain or SSL).

    Unresolved include directive in modules/ROOT/pages/managing-connections.adoc - include::2.8@c-sdk::page$managing-connections.adoc[]

    It is not currently possible to use couchbase.cluster.Cluster to connect with a custom SSL certificate and password authentication. There is a JIRA issue logged for this here. Until this is fixed, the user can authenticate by instead calling the couchbase.bucket.Bucket constructor as follows:

    connstr = 'couchbases://{hostname}/{bucketname}?certpath={cert_path}'.format(hostname=hostname,

    From Couchbase Python Client 2.5.1, AlternateAddress is implemented, for connecting to nodes in a NATed environment, such as Docker containers using portmapping. It is on by default, if the server provides a topology that includes a multi-network configuration. Whichever network is selected at bootstrap will be logged.

    If using Docker Swarm, or otherwise running the SDK inside the NAT, then you will want to disable with ?network=default in the connection string, or an environmental setting can be made.

    Note that any SSL/TLS certificates must be set up at the point where the connections are being made. The Couchbase SDKs will honor any valid SSL/TLS certificates.