After almost three years since the last stable release, Watermill v1.2 is finally out!

If you’re new here, Watermill is our open-source library for building event-driven applications in Go, the easy way.

A lot has happened since v1.1. We’ve been running Watermill on production in many projects, using it in new ways and adding features to support new use cases. We also received a lot of feedback and contributions from the community.

Watermill grew to over 5.2k stars on GitHub and 39 contributors, counting just the main repository. We’ve added 4 new official Pub/Subs, and there are many unofficial integrations.

Celebrating the Launch

Meet the Gopher at our live event!

To celebrate the release, we plan to host a live event on March 1st at 5pm UTC. Join us on YouTube.

The planned agenda is as follows:

  • Watermill 1.2 Showcase.
  • Using Consumer Groups in Watermill - a live demo with examples.
  • Announcing our Event-Driven Training.
  • Coming next to Watermill (generics!).
  • A chance to win a unique crotchet Gopher.

What’s new?

You can find the full list of changes on the releases page. It’s long and includes many bug fixes and minor improvements, often from outside contributors (thank you, everyone!).

Below are highlights of the bigger changes.

The Forwarder Component

One of the best use cases for Watermill is publishing messages in transactions (AKA the outbox pattern). I wrote about it before in When an SQL database makes a great Pub/Sub featuring a Watermill example.

The Forwarder component provides a universal mechanism for this behavior: forwarding messages from one Pub/Sub to another (e.g., from SQL to Kafka).

It’s a high-level API on top of the Router, so it’s even easier to forward messages.

Forwarder has its own documentation entry and a complete example. It was contributed by Grzegorz Burzyński.

The FanIn Component

We already had the FanOut component before. It takes a single stream of messages and re-publishes them on a few topics.

FanIn does the opposite: it takes a collection of topics and merges the messages from them into a single stream.

FanIn has its own documentation entry. It was contributed by Michał Sokołowski.

I’m thrilled to see it’s possible to write such components on top of existing structures. It shows that Watermill’s abstractions follow the UNIX philosophy of modular components that work well together.

New Supported Pub/Subs

New Examples

Server-Sent Events example

SSE is our preferred way of pushing updates from the server. It’s simpler than WebSockets and plays nicely with Watermill’s abstractions.

See the example on the Watermill repository.

Exactly-once delivery example

Exactly-once delivery is not possible in most setups, but there’s one specific scenario where you can achieve it.

See the example on the Watermill repository.

Adding handlers while the Router is running

It’s now possible to add handlers to a running Router. Previously, all handlers had to be set up before starting it.

New CI

We moved the CI from CircleCI to GitHub Actions. It’s better integrated with GitHub’s PRs, and the configuration is simpler. All Pub/Subs now use the workflows defined in the main repository.

All repositories now use golangci-lint for static analysis.

Awesome Watermill

We’ve added the Awesome Watermill page with a list of unofficial libraries. Please add a PR if you know a repository that should appear there!

Watermill Contributors

Without contributors, Watermill wouldn’t be where it is today.

Writing a Pub/Sub integration is an especially high-impact project. To support the authors, we now keep a dedicated private channel on our discord server where they can reach us directly. The authors of Pub/Sub integrations keep write access to the repository after it’s transferred to the ThreeDotsLabs organization.

Let us know if you want to join this community and have your Pub/Sub integration officially supported.


As always, if something’s not clear, check out If you can’t find the answer there, join our discord server and ask your questions on the #watermill channel.

If you’d like to get some open-source experience and contribute to Watermill, we’ve prepared a list of good first issues.