Couchbase connection strings are surprisingly flexible, and most people only ever use a tiny fraction of their power.
Let’s see it in action. Imagine you have a Couchbase cluster running locally on port 11210, and you want to connect to it using the SDK. A basic connection string might look like this:
couchbase://localhost:11210
This tells the SDK to connect to a single node at localhost on the default memcached port, which Couchbase uses for cluster membership and data operations.
But what if you have multiple nodes? You can list them all, separated by commas:
couchbase://node1.example.com:11210,node2.example.com:11210,node3.example.com:11210
The SDK will then use these as entry points to discover the rest of the cluster. It doesn’t matter which node you list first; the SDK will bootstrap itself and figure out the topology.
Now, consider security. If your cluster is running with TLS/SSL enabled, you’ll want to use couchbases:// instead. This is a crucial distinction.
couchbases://node1.example.com:11207,node2.example.com:11207
Notice the port change to 11207, which is the default for secure Couchbase communication. The SDK will attempt to establish a TLS connection and verify the server certificates.
What about authentication? You can embed username and password directly into the connection string. This is convenient for quick scripts but less secure for production applications where credentials should ideally be managed separately.
couchbase://myuser:mypassword@localhost:11210
Or for a secure connection:
couchbases://myuser:mypassword@node1.example.com:11207,node2.example.com:11207
The SDK will use these credentials to authenticate with the cluster. If authentication fails, you’ll typically get an access denied error.
The command-line interface (CLI) tools, like couchbase-cli, also use connection strings, though their syntax can sometimes differ slightly or require specific flags. For couchbase-cli, you often specify the host and then use flags for ports, username, and password. However, for simpler cases or when interacting with specific commands that accept a direct connection string, the SDK format is generally understood.
For example, to get cluster information using couchbase-cli with authentication:
couchbase-cli cluster-info -c couchbase://myuser:mypassword@localhost:11210
The real power comes when you start thinking about the bucket parameter. You can specify a default bucket to connect to directly within the connection string. This is incredibly useful for applications that primarily interact with a single bucket.
couchbase://myuser:mypassword@localhost:11210/my-data-bucket
If you’re using TLS:
couchbases://myuser:mypassword@node1.example.com:11207/my-data-bucket
This pre-selects the bucket, so you don’t have to explicitly specify it in your SDK calls. It’s a minor optimization but can clean up your code.
The SDKs also support various options that can be appended as query parameters to the connection string. These allow fine-grained control over connection behavior. For instance, you can set the operation_timeout or kv_timeout.
couchbase://myuser:mypassword@localhost:11210/my-data-bucket?operation_timeout=5000&kv_timeout=2500
Here, operation_timeout is set to 5000 milliseconds (5 seconds) and kv_timeout to 2500 milliseconds (2.5 seconds). These timeouts are critical for preventing requests from hanging indefinitely if a node becomes unresponsive. The SDK will abort operations that exceed these durations.
One of the most powerful, yet often overlooked, aspects of connection strings is their ability to define custom DNS SRV records. If your Couchbase cluster is configured with SRV records, you can point your connection string to a domain name, and the SDK will automatically discover the cluster members and their ports. This is a more advanced setup, typically used in dynamic or cloud-native environments where node IPs can change frequently. The format would look something like:
couchbase://_couchbase._tcp.my-couchbase-domain.example.com
The SDK will then query DNS for SRV records associated with this service name to find available nodes. This abstracts away the underlying cluster topology and makes connections resilient to infrastructure changes.
Beyond the basic connection parameters, you can also specify options like durability_level or analytics_link directly in the connection string, allowing you to configure specific cluster interactions at the connection level. For example, to ensure data is written with a certain durability guarantee:
couchbase://myuser:mypassword@localhost:11210/my-data-bucket?durability_level=majority
This tells the SDK to only acknowledge a write operation once it has been replicated to a majority of nodes in the cluster, providing a stronger guarantee against data loss.
The next step is understanding how to configure connection pooling for optimal performance.