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 an options block when creating the Cluster instance. Here’s an example that configures several settings by passing the optional third argument to cbcolumnar.NewCluster():
cluster, err := cbcolumnar.NewCluster(
connStr,
cbcolumnar.NewCredential(username, password),
cbcolumnar.NewClusterOptions().
SetTimeoutOptions(
cbcolumnar.NewTimeoutOptions().
SetConnectTimeout(30*time.Second).
SetQueryTimeout(2*time.Minute),
).
SetSecurityOptions(cbcolumnar.NewSecurityOptions().
SetCipherSuites([]string{"MY_APPROVED_CIPHER_SUITE"}),
),
)
handleErr(err)Note: Options blocks can created using builder-style functions, like above, or by assigning to the struct fields directly.
| 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 for executing the query when no deadline is applied by |
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 Go runtime) |
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 Go reference documentation for a list of supported cipher suite names. |
|
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. |
Unmarshaler
The SDK uses a component called an Unmarshaler to convert query result rows into Go typed. The default implementation is JSONUnmarshaler, a thin wrapper around json.Unmarshal from "encoding/json".
This cluster option specifies the default unmarshaler.
You can override the unmarshaler for a specific query by setting the Unmarshaler query option when executing the query.