Managing Connections Using the PHP SDK with Couchbase Server
This section describes how to connect the PHP 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.
To manage Couchbase Server connections, you need to configure the client, connect to a bucket, and configure SSL.
To configure the client, instantiate a new
$myCluster = new CouchbaseCluster('couchbase://10.4.4.1,10.4.4.2,10.4.4.3');
In addition to the connection string passed to the
Cluster object, you can include a username and password.
The username and password are required to perform management operations against your cluster.
If you do not use the cluster management aspects of the SDK, the username and password parameters are optional.
Keep in mind that these credentials are the same ones you use to log in to the Couchbase administrator console, not those specified for the bucket itself.
Regular authentication is where you provide a password to the
It is also possible to define all credentials in single place, and associate with a container, which can be used for all future connections.
Since version 2.3.0, the PHP SDK provides the interface
\Couchbase\Authenticator which is implemented by all credentials containers.
The library can pull authentication parameters from it when necessary.
At the moment there is only one implementation of this interface:
\Couchbase\ClassicAuthenticator, but upcoming releases will also have RBAC support.
The use of the authenticator is simple:
$authenticator = new \Couchbase\ClassicAuthenticator(); $authenticator->cluster('Administrator', 'password'); $authenticator->bucket('protected', 'secret'); $cluster = new \Couchbase\Cluster("couchbase://localhost"); $cluster->authenticate($authenticator); $cluster->openBucket('protected'); // successfully opens connection $cluster->manager()->createBucket('hello'); // automatically use admin credentials
It is still possible to provide a password to the
manager() method, which will take precedence over the authenticator.
Such behaviour is discouraged, and future implementations of the
\Couchbase\Authenticator interface are likely to prevent mixing of authentication sources.
You can shortcut using the
authenticator() method, if you don’t need to reuse the credentials in several instances of
authenticate(), replacing it with
$cluster = new CouchbaseCluster("couchbase://localhost"); $cluster->authenticateAs('Administrator', 'password');
To connect to a bucket, call the
openBucket() method against your
Cluster instance, passing in the name of the bucket that you want to connect to.
If no bucket name is specified, the default bucket is opened.
The following example shows how to connect to a bucket:
$myCluster = new CouchbaseCluster(); $myBucket = $myCluster->openBucket('default');
In addition to the bucket name, you can optionally include the bucket password if one has been defined, as shown in the following example:
$myCluster = new CouchbaseCluster(); $myBucket = $myCluster->openBucket('default', 'password');
To close the connection to a bucket, call its
This method queues the disconnection of all open connections and causes any pending operations to fail.
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).
PHP SDK by default uses persistent connections to reuse underlying IO objects if the connection strings are the same.
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.
Couchbase Sever features the ability to have clients communicate securely via SSL.
To use SSL, you need Couchbase Server Enterprise 3.0 or later (not available in the Community Edition).
Obtain the SSL certificate used by the Cluster
Make the certificate available to the file system of the client host.
couchbases://scheme for the connection string.
Specify the local path to the certificate as the value for the
To connect to a bucket on an SSL-enabled Cluster at the node 10.3.4.33, with the certificate saved as
You can specify multiple hosts in the connection string so that the client may be able to connect even if the cluster topology changed. To specify multiple hosts, separate them using a comma:
See Failure Considerations for the C (libcouchbase) SDK in Couchbase for more information about handling cluster topology changes.
|You are not required to enumerate or pass all Couchbase cluster nodes to the client. The client only needs to know about a single node which is a member of the cluster. Once the client has connected to the node, it will query that node about the cluster topology, which in turn contains information about all Couchbase nodes and the services they contain.|
As an alternative to specifying multiple hosts in your program, you can get the actual bootstrap node list from a DNS SRV record. The following steps are necessary to make it work:
Set up your DNS server to respond properly from a DNS SRV request.
Enable it on the SDK and point it towards the DNS SRV entry.
Your DNS server should be set up like this (one row for each bootstrap node):
_couchbase._tcp.example.com. 3600 IN SRV 0 0 11210 node1.example.com. _couchbase._tcp.example.com. 3600 IN SRV 0 0 11210 node2.example.com. _couchbase._tcp.example.com. 3600 IN SRV 0 0 11210 node3.example.com.
|The ordering, priorities, and weighting are completely ignored and should not be set on the records to avoid ambiguities.|
If you plan to use secure connections, you use
_couchbases._tcp.example.com. 3600 IN SRV 0 0 11207 node1.example.com. _couchbases._tcp.example.com. 3600 IN SRV 0 0 11207 node2.example.com. _couchbases._tcp.example.com. 3600 IN SRV 0 0 11207 node3.example.com.
In the above example, you would specify
couchbase://example.com as the bootstrap host, and the library would check for the record.
If no such record exists, it will treat
example.com as an ordinary bootstrap node and try to bootstrap from it.
Note that if you pass more than one bootstrap host, DNS SRV lookup will not be attempted, and the hosts will be interepreted as normal Couchbase nodes.
In environments when lots of short-lived connections are made to Couchbase (for example, a small command-line utility or a fork-and-execute CGI application) the overhead in actually bootstrapping the client may be significant. This is because the client must retrieve the configuration from the cluster, and involves several additional TCP requests and in many cases an additional TCP connection.
You can bypass the initial network bootstrap phase by using the
config_cache directive in the connection string.
config_cache option accepts a path to a local file (the file should not exist when using for the first time).
When performing the bootstrap process, the client will first check the contents of the given file to see if it contains an existing cluster configuration, and if it does, will use the file as the bootstrap source.
If the file does not contain a configuration the client will then retrieve the configuration from the network and then write it to the file, so that future attempts will use the configuration file.
You can pass additional options in the connection string using the URL query format:
A list of options may be found in Client Settings