Introduction

Iggy provides official client SDKs in multiple languages. The Rust SDK is the most feature-complete, offering both a high-level API (with auto-batching, consumer groups, offset management, retry logic) and a low-level API for direct protocol operations.

Python, C++, and PHP wrap the Rust SDK, so they inherit all transport protocols when using connection strings. Java and C# implement TCP and HTTP natively. Go and Node.js currently support TCP only.

The Rust SDK is always the first to receive new features.

Server compatibility

Server 0.9.0 introduced a new binary wire protocol shared by all SDKs, and the SDKs don't fall back to the older one. Use the SDK version that matches your server:

The C++ and PHP SDKs are not published to a registry. Build them from the same source checkout as the server.

Prerequisites

The examples below use the iggy/iggy root credentials. For a new local development instance, with no IGGY_ROOT_USERNAME or IGGY_ROOT_PASSWORD overrides, use:

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

--fresh wipes this replica's local data directory. In a cluster, it can recover stored credentials from another replica. The environment takes precedence over the default-credentials flag, and bootstrap settings do not replace recovered credentials. This setup is for development only; use a disposable data directory. See Connection Strings for the authentication details.

Connection string

Connection strings are supported by the Rust, Python, C++, and PHP SDKs. They provide a compact way to configure the client, including the transport protocol, credentials, server address, and options.

Format:

iggy://username:password@host:port[?options]

Transport selection via scheme:

Personal Access Token authentication: any credential without a colon is treated as a PAT. Server-minted tokens carry no prefix, so paste the token exactly as returned:

iggy://<personal-access-token>@host:port

Examples:

The Rust snippets assume an async Tokio context. HTTP requires an explicit login after construction; connection-string credentials are applied automatically only by the binary transports.

use iggy::prelude::*;

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

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

// Rust - TCP with options
let client = IggyClient::from_connection_string(
    "iggy://iggy:iggy@127.0.0.1:8090?nodelay=true&reconnection_retries=unlimited&heartbeat_interval=5s"
)?;

from apache_iggy import IggyClient

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

The option keys differ per transport and unknown keys are rejected as hard errors. See Connection Strings for the full per-transport option tables, defaults, and default ports.

Common operations

The Rust SDK exposes these operations through traits on IggyClient. Availability and method names vary across foreign SDKs and transports:

• SystemClient - ping, stats, snapshot
• StreamClient - create, get, list, update, delete, purge streams
• TopicClient - create, get, list, update, delete, purge topics
• PartitionClient - create, delete partitions
• SegmentClient - delete segments
• MessageClient - send, poll messages
• ConsumerOffsetClient - get, store, delete consumer offsets
• ConsumerGroupClient - create, get, list, delete consumer groups
• UserClient - create, get, list, update, delete users, change password, update permissions
• PersonalAccessTokenClient - create, list, delete PATs
• ClusterClient - cluster metadata

Polling strategies

When polling messages, you can choose from several strategies (Rust method names are shown):

Partitioning strategies

When sending messages, you can control partition routing (Rust method names are shown):

The Rust SDK resolves these strategies before sending a binary request. The Rust HTTP client and Node SDK send the strategy to the server for resolution.