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 and C++ 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.

Connection string

Connection strings are supported by Rust, Python, and C++ 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:

iggy://iggypat-your-token-here@host:port

Examples:

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

// Rust - QUIC with TLS
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")

Available TCP options: tls, tls_domain, tls_ca_file, reconnection_retries (number or unlimited), reconnection_interval, reestablish_after, heartbeat_interval, nodelay

Available QUIC options: response_buffer_size, max_concurrent_bidi_streams, datagram_send_buffer_size, initial_mtu, send_window, receive_window, keep_alive_interval, max_idle_timeout, validate_certificate, heartbeat_interval, reconnection_max_retries, reconnection_interval

Available WebSocket options: tls, tls_domain, tls_ca_file, heartbeat_interval, reconnection_retries, reconnection_interval, read_buffer_size, write_buffer_size, max_message_size, max_frame_size

Available HTTP options: heartbeat_interval, retries

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