Skip to content

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 ───────┘

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.

Username and password go in the userinfo part of the URI, before the host. Percent-encode any reserved character.

kurrentdb://admin:changeit@localhost:2113
kurrentdb://user%40domain:p%40ssw%3Ard@localhost:2113

Certificate credentials come from userCertFile and userKeyFile instead. When both are set they take precedence over a username and password.

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

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.

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
Parameter Type Default Meaning
connectionName string generated Label that appears in server-side connection metrics

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 deadline

A duration may carry an ms or s suffix, which overrides the unit above.

?keepAliveInterval=500ms&discoveryInterval=2s

The 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.

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.

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=10s
options.ToConnectionString(legacy: true); // keepAliveInterval=10

The 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.