Connection String Reference
A connection string names the nodes to reach and configures how the client talks to them. The format is shared across every KurrentDB SDK, so a string written for one client means the same thing here.
kurrentdb+discover://admin:changeit@node1:2113,node2:2113?tls=true&nodePreference=leader└── scheme ──────┘ └ credentials ┘ └───── hosts ──────┘ └────── parameters ───────┘Schemes
Section titled “Schemes”Six schemes parse. The esdb and eventstore forms are aliases kept for connection strings written
against the older clients.
| Scheme | Topology |
|---|---|
kurrentdb:// |
A single node, addressed directly |
kurrentdb+discover:// |
A cluster, discovered through gossip |
esdb:// |
Alias for kurrentdb:// |
esdb+discover:// |
Alias for kurrentdb+discover:// |
eventstore:// |
Alias for kurrentdb:// |
eventstore+discover:// |
Alias for kurrentdb+discover:// |
A string carrying more than one host must use a discovery scheme. Several hosts under a direct scheme is a configuration error, because a direct connection addresses exactly one node.
Credentials
Section titled “Credentials”Username and password go in the userinfo part of the URI, before the host. Percent-encode any reserved character.
kurrentdb://admin:changeit@localhost:2113kurrentdb://user%40domain:p%40ssw%3Ard@localhost:2113Certificate credentials come from userCertFile and userKeyFile instead. When both are set they
take precedence over a username and password.
Parameters
Section titled “Parameters”Transport security
Section titled “Transport security”| Parameter | Type | Default | Meaning |
|---|---|---|---|
tls |
boolean | true |
Whether to connect over TLS. Set false only for an insecure local node |
tlsVerifyCert |
boolean | true |
Whether to verify the server certificate. false silences certificate errors, including a genuine one |
tlsCaFile |
path | none | CA bundle to verify against, when the cluster certificate is signed by a private CA |
userCertFile |
path | none | Client certificate for certificate authentication |
userKeyFile |
path | none | Private key for userCertFile |
userKeyPassword |
string | none | Password protecting userKeyFile |
Discovery
Section titled “Discovery”Applies to the +discover schemes.
| Parameter | Type | Default | Meaning |
|---|---|---|---|
nodePreference |
enum | leader |
Which node to prefer. leader, follower, random, or readOnlyReplica |
maxDiscoverAttempts |
number | 10 |
How many times to attempt discovery before failing |
discoveryInterval |
milliseconds | 100 |
Wait between discovery attempts |
gossipTimeout |
seconds | 5 |
Deadline for a single gossip request |
readPreference is accepted as a synonym for nodePreference, and wins if a string somehow carries
both.
Connection health
Section titled “Connection health”| Parameter | Type | Default | Meaning |
|---|---|---|---|
keepAliveInterval |
seconds | 10 |
Wait between keepalive pings on an idle connection |
keepAliveTimeout |
seconds | 10 |
Deadline for a keepalive ping before the connection is considered dead |
defaultDeadline |
milliseconds | none | Deadline applied to a call that sets none of its own |
Identification
Section titled “Identification”| Parameter | Type | Default | Meaning |
|---|---|---|---|
connectionName |
string | generated | Label that appears in server-side connection metrics |
Duration units
Section titled “Duration units”The unit is fixed per parameter, and it is the unit the other KurrentDB SDKs use. It is not uniform across parameters.
| Unit | Parameters |
|---|---|
| seconds | keepAliveInterval, keepAliveTimeout, gossipTimeout |
| milliseconds | discoveryInterval, defaultDeadline |
A value of -1 means no limit, and carries no unit.
?keepAliveInterval=10 10 seconds?gossipTimeout=5 5 seconds?discoveryInterval=100 100 milliseconds?defaultDeadline=-1 no deadlineExplicit units
Section titled “Explicit units”A duration may carry an ms or s suffix, which overrides the unit above.
?keepAliveInterval=500ms&discoveryInterval=2sThe suffix is specific to this client. A string carrying one does not parse in the Java, Go, Rust, Node.js or Python clients, so keep to the bare form for anything shared between SDKs.
Validation
Section titled “Validation”KurrentClientOptions.Parse validates and throws. A duration that is negative, other than -1, or
zero is rejected rather than reaching a live connection. keepAliveTimeout must not be greater than
keepAliveInterval.
Generating a connection string
Section titled “Generating a connection string”ToConnectionString renders options back into a string. Durations carry an explicit unit by default,
which round-trips exactly. Pass legacy: true for the bare form the other clients read.
options.ToConnectionString(); // keepAliveInterval=10soptions.ToConnectionString(legacy: true); // keepAliveInterval=10The legacy form carries whole units only, so a sub-second value rounds down. ToString() returns the
default form.
ToConnectionString omits parameters left at their default.