# Connection Strings

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

Rendered page: https://iggy.apache.org/docs/sdk/connection-strings/

Source: https://github.com/apache/iggy-website/blob/main/content/docs/sdk/connection-strings.mdx

Docs version: server 0.9.0, Rust SDK 0.11.0, CLI 0.14.0, Node.js SDK 0.10.0, and the Python, Java, Go and C# SDKs at 0.9.0

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

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

The host and port are **always required**. Use a hostname or IPv4 address. The parser rejects IPv6 forms such as `[::1]:8090`. Options are appended as `key=value` pairs separated by `&`. Scheme names and option keys are case-sensitive.

The parser does not percent-decode credentials or option values. Reserved separators such as `:` and `@` cannot be escaped inside a username or password; use a PAT for credentials that contain them. Duplicate option keys use the last value. Boolean options enable only for the literal `true`; use `false` to disable them.

**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:

```text
iggy://username:password@127.0.0.1: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:

```text
iggy://<personal-access-token>@127.0.0.1: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 examples use `iggy`/`iggy`. For a new local development instance, with no `IGGY_ROOT_USERNAME` or `IGGY_ROOT_PASSWORD` overrides, use:

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

The environment takes precedence over the flag. Stored or recovered root credentials are not replaced by bootstrap settings. `--fresh` deletes this replica's local data; in a cluster it can recover committed state, including credentials, from another replica. Use this reset only for disposable development data. A new standalone server without explicit credentials generates a root password; a new cluster requires explicit root credentials.

TCP, QUIC, and WebSocket apply connection-string credentials during `connect()`. HTTP requires an explicit login, as described below.

## 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. Heartbeat and reconnection intervals must be greater than zero; the reconnection cooldown can be zero.

## TCP options

| Key | Description | Default |
|-----|-------------|---------|
| `tls` | Enable TLS (`true`/`false`) | `false` |
| `tls_domain` | Name for TLS validation; when empty, use the dialed hostname or IP | empty |
| `tls_ca_file` | PEM file of trusted CA certificates, replacing the built-in roots | none |
| `reconnection_retries` | Retry passes over known endpoints after the initial pass, or `unlimited` | `unlimited` |
| `reconnection_interval` | Duration between retry passes | `1s` |
| `reestablish_after` | Cooldown measured from the last connection establishment | `5s` |
| `heartbeat_interval` | Duration between heartbeats | `5s` |
| `nodelay` | Enable `TCP_NODELAY` (`true`/`false`) | `false` |

```text
iggy://iggy:iggy@127.0.0.1:8090?tls=true&tls_domain=localhost&tls_ca_file=core/certs/iggy_ca_cert.pem&reconnection_retries=5&heartbeat_interval=3s&nodelay=true
```

With `tls=true`, TCP always validates the server certificate. Without `tls_ca_file`, it uses the built-in Mozilla roots. An explicit CA file can trust a private CA. The example above runs from the repository root against a TLS-enabled listener using the test certificate and key in `core/certs/iggy_cert.pem` and `core/certs/iggy_key.pem`. Those certificates are for local testing; see [Security](https://iggy.apache.org/docs/server/security) for TLS configuration.

## 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` | Maximum bytes read for one response | `10000000` |
| `max_concurrent_bidi_streams` | Maximum concurrent peer-initiated bidirectional streams | `10000` |
| `datagram_send_buffer_size` | Datagram send buffer size in bytes | `100000` |
| `initial_mtu` | Initial UDP payload size in bytes, clamped to at least `1200` | `1200` |
| `send_window` | Send window size in bytes | `100000` |
| `receive_window` | Connection receive window size in bytes | `100000` |
| `keep_alive_interval` | Keep-alive interval in milliseconds; `0` disables it | `5000` |
| `max_idle_timeout` | Idle timeout in milliseconds; `0` leaves Quinn's `30000` ms default | `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` | Cooldown measured from the last connection establishment | `5s` |

```text
iggy+quic://iggy:iggy@127.0.0.1:8080?validate_certificate=false&reconnection_max_retries=5
```

QUIC certificate validation is disabled by default. When enabled, it uses the platform verifier and the connection-string configuration's server name, `localhost`. For a different certificate name, use the Rust QUIC configuration builder's `with_server_name()` method. Values above QUIC's 62-bit limit for `max_concurrent_bidi_streams`, `receive_window`, or `max_idle_timeout` are rejected with `InvalidConfiguration`.

## 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` | Cooldown measured from the last connection establishment | `5s` |
| `read_buffer_size` | Read buffer size in bytes | `131072` |
| `write_buffer_size` | Target write buffer size in bytes | `131072` |
| `max_write_buffer_size` | Maximum write buffer size in bytes; must exceed `write_buffer_size` | `usize::MAX` |
| `max_message_size` | Maximum incoming WebSocket message size in bytes | `67108864` |
| `max_frame_size` | Maximum incoming frame payload size in bytes | `16777216` |
| `accept_unmasked_frames` | Has no effect on client connections | `false` |
| `tls` | Enable TLS (`true`/`false`) | `false` |
| `tls_domain` | Name for TLS validation; when empty, use the connected IP | empty |
| `tls_ca_file` | PEM file of trusted CA certificates when validation is enabled | none |
| `tls_validate_certificate` | Validate the server certificate (`true`/`false`) | `false` |

```text
iggy+ws://iggy:iggy@127.0.0.1:8092?heartbeat_interval=5s&max_message_size=1048576
```

WebSocket TLS does not validate the server certificate unless `tls_validate_certificate=true`. With validation enabled, `tls_ca_file` replaces the built-in Mozilla roots. Size limits cannot be removed through connection strings; use the WebSocket configuration object for an unlimited message or frame size.

## HTTP options

| Key | Description | Default |
|-----|-------------|---------|
| `heartbeat_interval` | Duration between heartbeats | `5s` |
| `retries` | Maximum retries for transient request failures | `3` |

```text
iggy+http://iggy:iggy@127.0.0.1:3000?retries=5
```

The HTTP scheme constructs a plain `http://` API URL. Use the Rust HTTP builder's `with_api_url()` for HTTPS. HTTP parses the credential field but does not log in with it. In Rust, call `login_user()` or `login_with_personal_access_token()` explicitly before protected requests.

## Usage

In Rust, construct clients inside a Tokio runtime, which QUIC needs even before `connect()`. The following snippet assumes an async function returning `Result<_, IggyError>` and the matching [Rust SDK setup](https://iggy.apache.org/docs/sdk/rust/intro).

```rust
use iggy::prelude::*;

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

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

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

// HTTP
let client = IggyClient::from_connection_string("iggy+http://iggy:iggy@127.0.0.1:3000")?;
client.login_user("iggy", "iggy").await?;
```

```python
from apache_iggy import IggyClient

client = IggyClient.from_connection_string("iggy://iggy:iggy@127.0.0.1:8090")
```

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