A newer version of this documentation is available.

View Latest

Managing server connections

Shows how to instantiate a client object to connect to a Couchbase cluster

Note that many of these examples will demonstrate a connection string. The connection string is interpreted by the underlying C library. You can read more about it at Managing server connections

Connecting to a bucket (synchronous API)

To connect to a bucket using the synchronous API, simply create a new Bucket object by calling its constructor. You should pass a connection string to the bucket indicating the host(s) and bucket you want to connect to. If your bucket is protected by a password, pass the password keyword argument to the constructor.

from couchbase.bucket import Bucket
bucket = Bucket('couchbase://10.1.1.1/default')
# With a password:
protected_bucket = Bucket('couchbase://10.1.1.1/default', password='s3cr3t')

The bucket connection will close 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.

Connecting to a bucket (Twisted API)

Connecting via the Twisted API is similar to the synchronous API. To connect via the Twisted API, create the Bucket object, then call the connect() method on the object. This method will return a Deferred which will have its callback invoked if the connection succeeds and its errback invoked on error.

from twisted.internet import reactor
from txcouchbase.bucket import Bucket

bucket = Bucket('couchbase://10.1.1./default')

def on_connect_ok(*ignored_args):
  print "Client connected OK"
def on_connect_fail(err, *args):
  print "Client failed ", err
  err.raiseException()

d = bucket.connect()
d.addCallback(on_connect_ok)
d.addErrback(on_connect_fail)

Configuring SSL

Read more about secure SSL connections: SSL Connections

To configure SSL, pass an SSL scheme (couchbases://) with your connection. Ensure you pass the certpath parameter which should point to the local path to the cluster’s certificate

bucket = Bucket('couchbases://10.1.1.1/default?certpath=/path/to/cluster/certificate.pem')

Performance, 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.