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.

Prerequisites

The samples across the SDK docs log in with the iggy/iggy root credentials. These only exist when the server is started with the default-credentials flag (or IGGY_ROOT_USERNAME/IGGY_ROOT_PASSWORD set) on its first boot. Otherwise root gets a generated password and the samples fail with InvalidCredentials:

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

--fresh wipes the local data directory, so an existing server with different stored credentials is re-initialized. This setup is for development only.

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:

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

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

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

# Python
client = IggyClient.from_connection_string("iggy://iggy:iggy@localhost: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

All SDKs provide the same core operations through the unified client interface:

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

Partitioning strategies

When sending messages, you can control partition routing:

Strategies resolve in the client on binary transports, and on the server for the HTTP API and the Node SDK.