Connection String Reference

Every Planck client reads the same connection string. One format, one parser, no per-language dialect. Once you have used it from Zig, you have effectively used it from everything else.

Format

host:port;uid=<username>;key=<base64-key>;tls=true|false

The address comes first, and after that a ; delimited list of key=value pairs. The order of pairs does not matter. Unknown keys are simply ignored, which is what keeps older clients working when newer ones go and add options.

The parser splits the address on the last : in the first segment, so a bracketed IPv6 literal is not supported. Kindly use a hostname or an IPv4 address only.

Parameters

Parameter	Required	Description
host	yes	Server hostname or IPv4 address (for example 127.0.0.1, db.example.com).
port	yes	Server TCP port. There is no implicit default in the parser.
uid	when secured	Username for authentication.
key	when secured	Base64 encoded authentication key.
tls	no (default no)	true enables TLS 1.3 on the wire. Anything else, including absent, is off.

uid and key are required whenever the server has security enabled, which is the default anyway. In case you have explicitly disabled security on the server, you can leave both off and the client will skip the authentication round trip.

The standard listening port for a fresh install is 23469. Do note that this is a server side setting and not a client default, so always include the same in your string.

Examples

Local dev against an unsecured server:

127.0.0.1:23469

Local dev with the default admin credentials:

127.0.0.1:23469;uid=admin;key=NH8ohl2LHDT8xSJbHGPAsCluCh5pe8Ldn+hckcJovXk=

Production over TLS:

db.example.com:23469;uid=myapp;key=abc123base64key==;tls=true

Non standard port, TLS on:

192.168.1.100:9000;uid=admin;key=mykey==;tls=true

The default admin user

On the first startup with security enabled, the server creates an admin user and prints a freshly generated key to the server log. That key itself is the one you paste into key= for your first connection. From there onwards you should rotate it.

In case you have lost the log line, the server side planctl tool can reset and reprint the same. The connection string by itself has no way to recover credentials.

TLS

Planck speaks TLS 1.3 and nothing older than that. You can toggle it from the client by appending ;tls=true.

In a mono app, the default posture is TLS 1.3 with a self signed certificate. The client connects, completes the handshake, and does not verify the server certificate chain. This matches the deployment posture where the server, the data, and the workload all sit behind the same trust boundary, and it lets ;tls=true work out of the box without any CA dance.

When you do have a real certificate, configure it on the server in config.yaml under tls. On the client side you still just need ;tls=true. As such, if Planck sits behind a TLS terminating proxy, leave ;tls=true off and let the proxy handle the same.

What the connection string does not configure

The connection string is intentionally narrow. Anything that varies per call, per process, or per environment lives in the client API and not in the string. In particular:

• Retry policy, timeouts, and the circuit breaker are configured on the client instance after construction (setRetryPolicy, setTimeoutConfig, setCircuitBreaker in the Zig client). They do not live in the connection string.
• There is no ca, verify, or cert parameter. The mono app default covers the common case. For anything beyond that, the surrounding server configuration is the right knob.
• There are no environment variable overrides. The server reads config.yaml. The client reads only the connection string you hand it, and that is it.

Reconnection behavior

reconnect() on the native client reuses the original connection string. This means the TLS choice, the credentials, and the host all carry across the reconnect:

1. Close the existing TCP socket.
2. Open a new one to the same host and port.
3. Re run the TLS 1.3 handshake if the original connection had tls=true.
4. Re authenticate with the same uid and key.

Calling code does not need to stash the connection string itself; the client holds onto the same for the lifetime of the instance.

Using it from Zig

const planck = @import("planck");

var client = try planck.Client.init(allocator, io);
defer client.deinit();

var auth = try client.connect(
    "127.0.0.1:23469;uid=admin;key=UGxhbmNrX0RlZmF1bHRfQWRtaW5fS2V5XzAwMTA=;tls=false",
);
defer auth.deinit();

connect returns an AuthResult carrying the session role and capabilities. Read whatever you need from it and then deinit() it. Every other Planck client takes the same string and behaves the same way on it.