Client Settings
Change the SDK’s behavior by configuring client settings.
Client settings can be configured by writing code, or by including parameters in the connection string.
Configure with Code
To configure SDK client settings by writing code, provide a configuration callback when creating the Cluster instance. Here’s an example that configures several settings by passing the optional third argument to Cluster.newInstance():
Cluster cluster = Cluster.newInstance(
connectionString,
Credential.of(username, password),
clusterOptions -> clusterOptions (1)
.timeout(timeoutOptions -> timeoutOptions (2)
.connectTimeout(Duration.ofSeconds(30))
.queryTimeout(Duration.ofMinutes(2))
) (3)
.security(securityOptions -> securityOptions (4)
.cipherSuites(List.of("MY_APPROVED_CIPHER_SUITE"))
)
);| 1 | The parameter type is Consumer<ClusterOptions>.
The SDK passes a ClusterOptions object to your consumer.
Configure the options by calling methods on the given object. |
| 2 | The same callback pattern extends to the sub-builders for different categories. For example, ClusterOptions.timeout() takes a Consumer<TimeoutOptions>. |
| 3 | The *Options classes are mutable builders.
Every method returns the same builder, allowing for method call chaining. |
| 4 | Most users won’t need to configure security settings, but it’s shown here for completeness. |
| You don’t need to call every method in the above example; call only the methods where you want to override the client setting’s default value. |
Configure with Connection String Parameters
Another way to configure client settings is to include parameters in the connection string. Here is an example connection string with two parameters:
couchbases://example.com?timeout.connect_timeout=30s&timeout.query_timeout=2mIf the same parameter name appears in the connection string more than once, the SDK uses the rightmost value.
If the same client setting is specified both in code and in the connection string, the SDK uses the value in the connection string.
| If your application reads the connection string from a config file (or other external source), you can change the connection string to override client settings without having to recompile your code. |
Durations
For client settings that represent durations, the connection string parameter’s value is specified using the format accepted by Golang’s time.ParseDuration method.
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
Note that although the Golang syntax allows negative durations, the SDK rejects non-positive timeout durations.
Client Settings Reference
This section describes all client settings supported by the SDK.
Timeout Options
Configuring timeouts gives you control over how long the SDK waits for operations to succeed or fail.
| Connection string parameter | Default value | Description |
|---|---|---|
|
Time limit for establishing a network connection. Indirectly controls SDK bootstrap timeout, which is 1.5 times this duration. |
|
|
Default query execution time limit. Can be overridden for specific queries by setting the |
Security Options
The SDK is secure by default. Unless configured to trust a different root certificate, it trusts only the Couchbase Capella certificate authority whose root certificate is bundled with the SDK.
You probably won’t need to configure the SDK’s security options unless:
-
You have special security compliance requirements that restrict the set of allowed TLS cipher suites.
-
You are a Couchbase employee working with an internal non-production hosted service, or a local server installation.
| Connection string parameter | Default value | Description |
|---|---|---|
Empty string / empty list (SDK uses any cipher suite supported by the JVM) |
Limits the set of cipher suites the SDK may use when negotiating secure connections to the server. Leave this at the default value unless you have special security compliance requirements. When specifying this as a connection string parameter, the value is a comma-delimited list with no whitespace. Consult your JVM reference documentation for a list of supported cipher suite names. |
|
N/A |
Setting this to You probably won’t need to do this unless you are a Couchbase employee. |
|
N/A |
Filesystem path of the PEM-encoded root certificate(s) to trust instead of the Couchbase Capella certificate authority (CA) root certificate bundled with the SDK. In the unlikely event the Couchbase Capella CA is compromised, you can use this to point the SDK at an updated CA certificate without having to immediately upgrade to a new version of the SDK (which will include the updated CA certificate and trust it by default). |
Danger Zone
Finally, there is one security option whose use is strongly discouraged in nearly all circumstances.
Setting security.disable_server_certificate_verification to true allows the SDK to connect to any server, regardless of whether the server presents a certificate trusted by the SDK.
| Disabling server certificate verification is roughly equivalent to sending your credentials and all data over an insecure connection. Don’t do this unless connecting to a server running locally on your development machine. |
Deserializer
The SDK uses a component called a Deserializer to convert query result rows into Java objects. The default implementation is JacksonDeserializer, a thin wrapper around a Jackson ObjectMapper.
By default, a Jackson ObjectMapper throws an exception if it encounters a JSON field that does not match the structure of the target class.
Here’s an example that shows how to configure the ObjectMapper with different behavior:
ObjectMapper mapper = JsonMapper.builder()
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) (1)
.build();
Cluster cluster = Cluster.connect(
connectionString,
Credential.of(username, password),
clusterOptions -> clusterOptions
.deserializer(new JacksonDeserializer(mapper))
);| 1 | Ignore unknown properties instead of throwing exception. |
This cluster option specifies the default deserializer.
You can override the deserializer for a specific query by setting the deserializer query option when executing the query.
If you prefer not to work with the Deserializer interface, you can always call row.bytes() to get a row’s content as a raw byte array.
Then you can process the byte array however you like.
|
Custom deserializers
Implement the Deserializer interface to add support for other JSON processing libraries.
The SDK source code repository includes examples for Gson and DSL-JSON that you can copy into your own project or use as a starting point for other libraries.