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.10.0 uses binary protocol 0.12.0. Upgrade clients and server together. There is no fallback to the 0.9 protocol. These are the component versions prepared for the upcoming release. Until publication, build the matching source release candidate.

C++ and PHP are included in the source archive. Swift uses the root Swift Package Manager manifest. See Upgrading before replacing an existing deployment.

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

Every SDK has connection-string support. Accepted schemes, credentials and options differ by language. Java currently accepts username/password TCP strings with tls and tls_ca_file only. 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 streams
• TopicClient - create, get, list, update, delete 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 HTTP API can resolve the strategy on the server. Binary clients route to the selected partition primary.

Read and recovery APIs

Use deferred polling to wait for messages. A partition reader groups partitions by primary, and a consumer hands messages to the application one at a time. PollOptions defines the count, wait, byte budget and commit policy. Manual commits are the shared default.

Resource creation accepts typed options. Updates use patches that change only supplied fields and can reset supported defaults. See Topic options and Stream options.

SDKs also expose metadata changes and raw requests to a selected replica. Recovery APIs differ. Swift does not expose retained mutation resolution or pending mutation limits. It has abandonment for uncertain committing reads. Read each language guide before implementing retries after an uncertain write.