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
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 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)
|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')
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.