From b200b63a4f8212225f55fb48cd0050c7b601766d Mon Sep 17 00:00:00 2001 From: William Chong Date: Tue, 14 Apr 2026 06:26:11 +0000 Subject: [PATCH 1/4] docs: fix gossipTimeout description --- docs/api/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index b0b2b9d0..30c72c47 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -75,7 +75,7 @@ There are a number of query parameters that can be used in the connection string | `connectionName` | Any string | None | Connection name | | `maxDiscoverAttempts` | Number | `10` | Number of attempts to discover the cluster. | | `discoveryInterval` | Number | `100` | Cluster discovery polling interval in milliseconds. | -| `gossipTimeout` | Number | `5` | Gossip timeout in seconds, when the gossip call times out, it will be retried. | +| `gossipTimeout` | Number | `5` | Gossip timeout in seconds. If the gossip call times out, the next candidate endpoint will be tried. | | `nodePreference` | `leader`, `follower`, `random`, `readOnlyReplica` | `leader` | Preferred node role. When creating a client for write operations, always use `leader`. | | `tlsVerifyCert` | `true`, `false` | `true` | In secure mode, set to `true` when using an untrusted connection to the node if you don't have the CA file available. Don't use in production. | | `tlsCaFile` | String, file path | None | Path to the CA file when connecting to a secure cluster with a certificate that's not signed by a trusted CA. | From 955111e42b024c5d7a3d690eb20abb67dcb50b7e Mon Sep 17 00:00:00 2001 From: William Chong Date: Tue, 14 Apr 2026 06:29:39 +0000 Subject: [PATCH 2/4] docs: clarify +discover uses single DNS endpoint only --- docs/api/getting-started.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index 30c72c47..edfe0017 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -35,33 +35,39 @@ mode, you must explicitly set `tls=false` in your connection string or client co KurrentDB uses connection strings to configure the client connection. The connection string supports two protocols: -- **`kurrentdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints) -- **`kurrentdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints +- **`kurrentdb://`** - for connecting to a single node, or to a multi-node cluster using multiple gossip seed endpoints +- **`kurrentdb+discover://`** - for connecting using DNS discovery with a single DNS endpoint -When using `kurrentdb://`, you specify the exact endpoints to connect to. The client will connect directly to these endpoints. For multi-node clusters, you can specify multiple endpoints separated by commas, and the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. +When using `kurrentdb://` with multiple endpoints separated by commas, the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. If one of the nodes is down, the client will try the next endpoint. -With `kurrentdb+discover://`, the client uses cluster discovery to find available nodes. This is particularly useful when you have a DNS A record pointing to cluster nodes or when you want the client to automatically discover the cluster topology. +With `kurrentdb+discover://`, the client resolves a single DNS endpoint to discover the cluster topology. This is useful when you have a DNS `A` record pointing to your cluster nodes. + +::: warning Only one host with +discover +When using `kurrentdb+discover://`, only a single host should be provided. If multiple hosts are specified, only the first one will be used for discovery and the rest will be ignored. If you need to specify multiple endpoints for redundancy, use `kurrentdb://` without `+discover` instead. +::: ::: info Gossip support Since version 22.10, kurrentdb supports gossip on single-node deployments, so `kurrentdb+discover://` can be used for any topology, including single-node setups. ::: -For cluster connections using discovery, use the following format: +For multi-node clusters where you know the individual node addresses, use multiple gossip seed endpoints: ``` -kurrentdb+discover://admin:changeit@cluster.dns.name:2113 +kurrentdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 ``` -Where `cluster.dns.name` is a DNS `A` record that points to all cluster nodes. +The client will try each endpoint in turn and use the Gossip API to discover the cluster topology and select the best node based on the configured node preference. -For direct connections to specific endpoints, you can specify individual nodes: +For cluster connections using DNS discovery, use a single DNS endpoint: ``` -kurrentdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 +kurrentdb+discover://admin:changeit@cluster.dns.name:2113 ``` -Or for a single node: +Where `cluster.dns.name` is a DNS `A` record that points to all cluster nodes. + +For a single node: ``` kurrentdb://admin:changeit@localhost:2113 From d79fc581735dc97e4fe31e47dab27f0713d5ae5c Mon Sep 17 00:00:00 2001 From: William Chong Date: Tue, 14 Apr 2026 06:38:10 +0000 Subject: [PATCH 3/4] docs: fix imprecise wording about endpoint ordering --- docs/api/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index edfe0017..711c88de 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -38,7 +38,7 @@ KurrentDB uses connection strings to configure the client connection. The connec - **`kurrentdb://`** - for connecting to a single node, or to a multi-node cluster using multiple gossip seed endpoints - **`kurrentdb+discover://`** - for connecting using DNS discovery with a single DNS endpoint -When using `kurrentdb://` with multiple endpoints separated by commas, the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. If one of the nodes is down, the client will try the next endpoint. +When using `kurrentdb://` with multiple endpoints separated by commas, the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. If one of the nodes is down, the client will try another endpoint. With `kurrentdb+discover://`, the client resolves a single DNS endpoint to discover the cluster topology. This is useful when you have a DNS `A` record pointing to your cluster nodes. @@ -57,7 +57,7 @@ For multi-node clusters where you know the individual node addresses, use multip kurrentdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 ``` -The client will try each endpoint in turn and use the Gossip API to discover the cluster topology and select the best node based on the configured node preference. +The client will use the Gossip API to discover the cluster topology and select the best node based on the configured node preference. For cluster connections using DNS discovery, use a single DNS endpoint: From 06705d619bb1debf7993c579027ee12511e066ad Mon Sep 17 00:00:00 2001 From: William Chong Date: Tue, 14 Apr 2026 06:42:11 +0000 Subject: [PATCH 4/4] docs: make gossipTimeout description mode neutral --- docs/api/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index 711c88de..a78aae99 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -81,7 +81,7 @@ There are a number of query parameters that can be used in the connection string | `connectionName` | Any string | None | Connection name | | `maxDiscoverAttempts` | Number | `10` | Number of attempts to discover the cluster. | | `discoveryInterval` | Number | `100` | Cluster discovery polling interval in milliseconds. | -| `gossipTimeout` | Number | `5` | Gossip timeout in seconds. If the gossip call times out, the next candidate endpoint will be tried. | +| `gossipTimeout` | Number | `5` | Timeout in seconds for each gossip request during cluster discovery. | | `nodePreference` | `leader`, `follower`, `random`, `readOnlyReplica` | `leader` | Preferred node role. When creating a client for write operations, always use `leader`. | | `tlsVerifyCert` | `true`, `false` | `true` | In secure mode, set to `true` when using an untrusted connection to the node if you don't have the CA file available. Don't use in production. | | `tlsCaFile` | String, file path | None | Path to the CA file when connecting to a secure cluster with a certificate that's not signed by a trusted CA. |