Sarama: Go Client Library for Apache Kafka, Maintained by IBM

Connecting Go Services to Apache Kafka

Sarama provides the low-level building blocks for Go programs to produce and consume messages on Apache Kafka: opening connections to brokers, sending batches of messages, joining consumer groups, committing offsets, and managing transactional state. It is a pure Go implementation with no cgo dependency.

The README describes it as an MIT-licensed Go client library for Apache Kafka, with API documentation on pkg.go.dev/github.com/IBM/sarama and a set of runnable examples in the examples/ directory. The library is used in applications that need to publish event streams, consume event streams reliably, and coordinate partition assignments across multiple consumer instances.

The repository was originally created at Shopify and is now maintained under the IBM GitHub organization. The README notes a wiki and a Google Group for Kafka client developers for broader community discussion. The SECURITY.md in the repository covers responsible vulnerability disclosure.

Compatibility Policy: Two Releases Plus Two Months

Sarama states a specific compatibility policy: it supports the two latest stable releases of Kafka and of Go, plus a two-month grace period for older releases. Older Kafka releases are noted as likely to still work, but not formally supported.

This policy has practical implications. When the Kafka project releases a new stable version, older supported versions fall out of Sarama's active compatibility window two releases later. A team running Kafka 3.x brokers while upgrading to a new Sarama release should verify their broker version is still in the supported window before the upgrade.

Sarama follows semantic versioning with Go module version numbering. The go.mod file uses retract directives to signal past versions that should not be used. Four ranges are retracted for known bugs: v1.32.0 for a producer hang on retry, v1.31.0 and v1.31.1 for a producer deadlock, v1.26.0 and v1.26.1 for a consumer fetch session allocation bug, and v1.24.1 through v1.25.0 for a consumer group metadata request issue. The retract declarations are visible to `go get` and `go mod tidy`, which will skip those versions automatically. Any dependency graph that locked to one of those ranges should be updated.

Producers, Consumer Groups, and the Admin API

Sarama's core surface covers both sides of Kafka: producing messages to topics and consuming messages from them. The library supports both a synchronous producer and an async producer, consumer groups with automatic partition rebalancing, and an admin client for managing topics, ACLs, consumer group offsets, and configuration.

The examples/ directory demonstrates the primary patterns:

- `examples/consumergroup/` shows how to implement a consumer group with the `ConsumerGroup` interface, handling session lifecycle and message claiming. - `examples/txn_producer/` demonstrates transactional message production for exactly-once delivery guarantees. - `examples/exactly_once/` provides a complete transactional consumer-producer pattern, consuming from one topic and producing to another in the same transaction. - `examples/sasl_scram_client/` shows SASL SCRAM authentication setup. - `examples/interceptors/` shows how to add producer and consumer interceptors for logging, tracing, or metric collection.

The admin client in admin.go handles cluster-level operations, and the admin_transactions.go file shows support for listing and describing transactional producers in the cluster.

The mocks subpackage provides in-process implementations of the producer and consumer interfaces, which allows unit tests to verify message production and consumption logic without a running Kafka cluster.

Adding Sarama to a Go Project

Sarama's module path is `github.com/IBM/sarama`, as declared in go.mod. The README directs users to the pkg.go.dev documentation page for API reference and to the examples/ directory for runnable programs. The library requires Go 1.26.0 or later, as stated in go.mod.

The declared dependencies tell the compression and authentication story: klauspost/compress and pierrec/lz4/v4 provide Snappy, GZIP, and LZ4 codec support for Kafka message compression; jcmturner/gokrb5/v8 covers Kerberos authentication for SASL/GSSAPI; and rcrowley/go-metrics provides the metrics collection interface used internally.

For development and testing, the repository uses Docker Compose to spin up Kafka brokers with Kafka 4.3.1 by default (configurable through the `KAFKA_VERSION` environment variable in docker-compose.yml). The compose file includes toxiproxy, a network proxy for simulating connection failures and latency, which the Sarama test suite uses to verify behavior under degraded network conditions.

Unit tests use the mocks subpackage and require no running Kafka instance. Functional tests require a running cluster and are gated behind the `functional` build tag, allowing CI to separate quick unit tests from slower integration tests.

Exactly-Once Semantics and Transactional Producers

Apache Kafka added transactional support to enable exactly-once semantics for producer-consumer pipelines. Sarama exposes this through its transactional producer and the exactly_once example, which demonstrates a pattern called consume-transform-produce: reading messages from an input topic, transforming them, and writing to an output topic as a single atomic Kafka transaction.

The exactly-once example in `examples/exactly_once/` shows the complete setup: initializing a transactional producer with a unique transactional ID, managing transaction begin and commit calls around the processing loop, and handling aborts when errors occur. This pattern guarantees that messages are written to the output topic exactly once even if the consuming application restarts mid-batch.

The `examples/txn_producer/` example demonstrates standalone transactional production without the consumer side, showing how to send multiple messages in a batch under a single transaction commit. These patterns require Kafka brokers configured with transaction support, which has been standard since Kafka 0.11.

The `add_offsets_to_txn_request.go` and `add_partitions_to_txn_request.go` files in the root directory reflect the Kafka protocol messages for transactional offset and partition management, illustrating how deeply Sarama implements the Kafka protocol rather than abstracting over it.

Authentication: SASL, SCRAM, Kerberos, and TLS

Sarama supports multiple authentication mechanisms for connecting to secured Kafka clusters. The examples/sasl_scram_client/ directory provides a working example of SASL SCRAM authentication, which is commonly used for username-password access control in managed Kafka services and on-premises clusters.

Kerberos authentication (SASL/GSSAPI) is supported through the jcmturner/gokrb5 library listed in go.mod. This mechanism is required in enterprise environments that use Kerberos as their central authentication system. The `alter_user_scram_credentials_request.go` and related files in the repository handle the Kafka API requests for managing SCRAM credentials programmatically.

TLS for transport encryption is supported by configuring the tls.Config on the Sarama configuration struct. The SECURITY.md covers Sarama's security disclosure policy and the supported authentication mechanisms in detail.

For teams migrating from a Kafka cluster that uses ZooKeeper to one using KRaft (Kafka's own Raft-based controller mode), the docker-compose.yml in the repository shows both configurations, reflecting that Sarama's test suite validates both deployment modes.

Sarama versus confluent-kafka-go and franz-go

Three Go Kafka clients appear regularly in comparisons: Sarama, confluent-kafka-go, and franz-go.

Confluent-kafka-go is the official Confluent client for Go. It wraps the C library librdkafka using cgo, which gives it a cgo dependency and makes cross-compilation more complex. It integrates with the Confluent Schema Registry and Confluent Cloud tooling. For teams using Confluent Cloud or heavily integrated with the Confluent ecosystem, confluent-kafka-go provides tight alignment with that platform's tooling.

Franz-go is a newer pure Go Kafka client (no cgo) focused on performance, with a different API design from Sarama. It is Apache-2.0 licensed. Franz-go targets high-throughput use cases and has a lower-level API structure.

Sarama's position is as the oldest and most widely adopted Go Kafka client, with a broad community example set, MIT licensing, a no-cgo dependency, and a mocks subpackage for unit testing. It tracks current Kafka releases with its two-release compatibility policy. Teams already using Sarama in large codebases have significant existing integration that does not translate directly to the other clients without rewriting.

The right choice depends on the deployment: teams on Confluent Cloud may prefer confluent-kafka-go for its ecosystem integration, teams building new high-throughput services may evaluate franz-go, and teams with existing Sarama integrations or those who need the mocks for unit testing have strong reasons to stay with Sarama.

Maintenance Status and License

The last push to the repository was on September 28, 2026. The most recent release is v1.61.1, published September 27, 2026, following v1.61.0 on September 22, 2026. Release cadence has been consistent through 2026, with multiple patch and minor releases across the year.

Sarama is MIT-licensed. MIT permits use in any product, commercial or otherwise, with no copyleft requirement. The only condition is retaining the copyright notice.

The tools/ directory contains command-line utilities described in the README as useful for testing, diagnostics, and instrumentation. These tools can inspect Kafka topics, consumer group offsets, and cluster state without writing application code, which is useful during development and troubleshooting.

The FAQ on the project wiki covers specific implementation questions. The README directs contributors to CONTRIBUTING.md for contribution guidelines and to the Sarama wiki for technical and design details. The CODE_OF_CONDUCT.md is present in the repository, indicating a formal community conduct standard.

Editorial conclusion

Sarama is the established Go client for Apache Kafka, suited for teams who need a library with long community history, a broad example set, and mocks for unit testing. The "2 releases + 2 months" policy means teams should track Kafka version support before upgrading Kafka brokers in production. For new projects on current Kafka versions and Go, Sarama, confluent-kafka-go, and franz-go all cover the core use cases; the choice between them typically comes down to the cgo dependency (absent in Sarama and franz-go), licensing model (MIT for Sarama, Apache-2.0 for franz-go), and whether the project needs Confluent Schema Registry or other Confluent Cloud integrations. Before adopting Sarama, review the CHANGELOG for the retracted versions to confirm none are in your dependency graph.

Frequently asked questions

Official sources

1. IBM/sarama on GitHub
2. Issues
3. License: MIT
4. README
5. Releases