Examples

A runnable getting-started example lives in the examples/go directory of the core repository. Its go.mod carries a replace directive pointing at the in-repo SDK, so the example always builds against the SDK source in the same checkout. The examples are exercised in CI via scripts/run-examples-from-readme.sh --language go.

Starting the server

The Go SDK speaks the VSR (Viewstamped Replication) wire protocol. Build the SDK and server from the same checkout for unreleased changes. The examples require Go 1.25 or newer and log in as iggy/iggy. From the repository root, start a disposable development server with no IGGY_ROOT_USERNAME or IGGY_ROOT_PASSWORD overrides:

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

--fresh wipes this replica's local data directory (local_data by default). Environment credentials take precedence over the flag, and bootstrap settings do not replace recovered credentials. A fresh cluster replica can recover credentials from peers. This setup is intended only for development and testing.

Getting started

The producer creates sample-stream and sample-topic (if missing) and sends 5 batches of 10 messages to partition 0. The consumer polls them from offset 0 and exits after 5 batches. Stream, topic, and partition IDs are 0-based. These repository examples use numeric stream and topic IDs 0, so create no other streams or topics before running the producer on the fresh server. Run the producer first.

Run both from the examples/go directory:

go run ./getting-started/producer/main.go
go run ./getting-started/consumer/main.go

Each consumer reads partition 0 independently, starting from offset 0 or the earliest retained message. Running several consumers reads the same messages; these examples do not join a consumer group.

Both binaries accept the same flags:

• --tcp-server-address - server address, default 127.0.0.1:8090
• --tls - enable TLS
• --tls-ca-file - path to a CA certificate file
• --tls-domain - TLS server domain name for SNI

TLS

From the repository root, start a disposable server with TLS enabled and the development certificates:

IGGY_TCP_TLS_ENABLED=true \
IGGY_TCP_TLS_CERT_FILE=core/certs/iggy_cert.pem \
IGGY_TCP_TLS_KEY_FILE=core/certs/iggy_key.pem \
cargo run --bin iggy-server -- --fresh --with-default-root-credentials

The same data and credential prerequisites apply. These certificates are for development only. Run the producer before the consumer with the TLS flags (paths relative to examples/go):

go run ./getting-started/producer/main.go --tcp-server-address localhost:8090 --tls --tls-ca-file ../../core/certs/iggy_ca_cert.pem
go run ./getting-started/consumer/main.go --tcp-server-address localhost:8090 --tls --tls-ca-file ../../core/certs/iggy_ca_cert.pem

For the code walkthrough, see the quick start on the intro page, which follows the same example.