The canonical reference for Iggy connection strings, covering every scheme, credential form and option.

A connection string configures an Iggy client in a single line: transport, credentials, server address, and options. This page is the canonical reference for every scheme, credential form, and option key.

Connection strings are supported by the Rust SDK and the SDKs that wrap it (Python, C++, PHP).

Format

iggy[+transport]://credentials@host:port[?option=value&option=value]

The host and port are always required. Options are appended as key=value pairs separated by &.

Unknown option keys are hard errors. The parser rejects the whole string with InvalidConnectionString instead of ignoring the key, so a typo fails fast rather than silently falling back to a default.

Transport selection

The scheme picks the transport. Each transport has its own default server port:

Scheme	Transport	Default server port
`iggy://`	TCP (default)	8090
`iggy+tcp://`	TCP	8090
`iggy+quic://`	QUIC	8080
`iggy+http://`	HTTP	3000
`iggy+ws://`	WebSocket	8092

Credentials

Two forms are accepted:

Username and password, separated by a colon. Both parts must be non-empty:

iggy://username:password@localhost:8090

Personal Access Token: any credential without a colon is treated as a PAT. Server-minted tokens are plain base64 strings with no prefix, so paste the token exactly as the server returned it:

iggy://<personal-access-token>@localhost:8090

Do not prepend anything to the token. Strings like iggypat-... appear only in Iggy's own test code. A real token with a prefix added will fail to log in.

The default iggy/iggy root credentials only exist when the server was started with --with-default-root-credentials (or with IGGY_ROOT_USERNAME/IGGY_ROOT_PASSWORD set) on its first boot. Otherwise the root user gets a generated password and samples using iggy:iggy fail with InvalidCredentials:

cargo run --bin iggy-server -- --fresh --with-default-root-credentials

Duration values

Options typed as durations take human-readable values such as 5s, 500ms, or 1m, unless a table below says the value is a plain number.

TCP options

Key	Description	Default
`tls`	Enable TLS (`true`/`false`)	`false`
`tls_domain`	Domain name for TLS validation	empty
`tls_ca_file`	Path to a CA certificate file	none
`reconnection_retries`	Number of reconnection attempts, or `unlimited`	`unlimited`
`reconnection_interval`	Duration between reconnection attempts	`1s`
`reestablish_after`	Duration to wait before reestablishing the connection	`5s`
`heartbeat_interval`	Duration between heartbeats	`5s`
`nodelay`	Enable `TCP_NODELAY` (`true`/`false`)	`false`

iggy://iggy:iggy@localhost:8090?tls=true&tls_domain=example.com&reconnection_retries=5&heartbeat_interval=3s&nodelay=true

QUIC options

The QUIC reconnection keys differ from TCP: reconnection_max_retries (not reconnection_retries) and reconnection_reestablish_after (not reestablish_after). Using the TCP names in a QUIC string is a hard error.

Key	Description	Default
`response_buffer_size`	Response buffer size in bytes	`10000000`
`max_concurrent_bidi_streams`	Maximum concurrent bidirectional streams	`10000`
`datagram_send_buffer_size`	Datagram send buffer size in bytes	`100000`
`initial_mtu`	Initial MTU	`1200`
`send_window`	Send window size	`100000`
`receive_window`	Receive window size	`100000`
`keep_alive_interval`	Keep-alive interval in milliseconds (number)	`5000`
`max_idle_timeout`	Maximum idle timeout in milliseconds (number)	`10000`
`validate_certificate`	Validate the server certificate (`true`/`false`)	`false`
`heartbeat_interval`	Duration between heartbeats	`5s`
`reconnection_max_retries`	Number of reconnection attempts, or `unlimited`	`unlimited`
`reconnection_interval`	Duration between reconnection attempts	`1s`
`reconnection_reestablish_after`	Duration to wait before reestablishing the connection	`5s`

iggy+quic://iggy:iggy@localhost:8080?validate_certificate=false&reconnection_max_retries=5

WebSocket options

Key	Description	Default
`heartbeat_interval`	Duration between heartbeats	`5s`
`reconnection_retries`	Number of reconnection attempts, or `unlimited`	`unlimited`
`reconnection_interval`	Duration between reconnection attempts	`1s`
`reestablish_after`	Duration to wait before reestablishing the connection	`5s`
`read_buffer_size`	Read buffer size in bytes	transport default
`write_buffer_size`	Write buffer size in bytes	transport default
`max_write_buffer_size`	Maximum write buffer size in bytes	transport default
`max_message_size`	Maximum WebSocket message size in bytes	transport default
`max_frame_size`	Maximum WebSocket frame size in bytes	transport default
`accept_unmasked_frames`	Accept unmasked frames (`true`/`false`)	transport default
`tls`	Enable TLS (`true`/`false`)	`false`
`tls_domain`	Domain name for TLS validation	empty
`tls_ca_file`	Path to a CA certificate file	none
`tls_validate_certificate`	Validate the server certificate (`true`/`false`)	`false`

iggy+ws://iggy:iggy@localhost:8092?heartbeat_interval=5s&max_message_size=1048576

HTTP options

Key	Description	Default
`heartbeat_interval`	Duration between heartbeats	`5s`
`retries`	Number of request retries	`3`

iggy+http://iggy:iggy@localhost:3000?retries=5

Usage

use iggy::prelude::*;

// TCP with default options
let client = IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;

// QUIC
let client = IggyClient::from_connection_string("iggy+quic://iggy:iggy@localhost:8080")?;

// WebSocket
let client = IggyClient::from_connection_string("iggy+ws://iggy:iggy@localhost:8092")?;

// HTTP
let client = IggyClient::from_connection_string("iggy+http://iggy:iggy@localhost:3000")?;

# Python
client = IggyClient.from_connection_string("iggy://iggy:iggy@localhost:8090")

When you need settings a connection string cannot express (a custom Encryptor, a Partitioner, and similar), start from IggyClientBuilder::from_connection_string() and extend the builder on top.

Connection Strings