Implementing CQRS in Go: A Practical Guide to Scalable Architecture

CQRS is one of those patterns that gets oversold, overcomplicated, and occasionally misdiagnosed as a cure for plain old CRUD boredom.

The useful version is much simpler: separate the code that changes state from the code that reads state, then let each side evolve for its own job. Martin Fowler describes CQRS as using a different model to update information than the one used to read it, while also warning that for most systems it adds risky complexity. Microsoft makes the same core point in more operational terms: separate read and write models so each can be optimised independently.

If you work in Go, that idea maps unusually well to the language. Go is good at explicit boundaries, small interfaces, boring data types, and use-case oriented packages. That makes basic CQRS in Go much less theatrical than it often looks in conference slides. You do not need event sourcing, Kafka, or three databases to start. In fact, both Microsoft’s CQRS guidance and Three Dots Labs’ Go examples show that a simple implementation can share the same underlying store, with separate command and query handlers added first and fancier infrastructure introduced only when the problem actually demands it.

What CQRS Actually Means

At the core, CQRS draws a hard line between commands and queries. A query reads data and should not modify the system’s state. A command changes state and should not return domain data as its main result. Three Dots Labs phrase this in practical Go terms: queries return data and commands make changes, with errors being a normal command result. That is the basic move. Everything else is optional.

A common misunderstanding is that CQRS automatically means separate databases, asynchronous projections, or event sourcing. That is not true. Microsoft’s pattern guide explicitly treats separate data stores as the more advanced form, not the default one, and Three Dots Labs show a Go implementation where queries read from the same database as writes because that is sufficient for the system at hand. If your article only teaches one thing clearly, make it this: CQRS is primarily a modelling and application-structure choice, not a mandatory distributed systems package deal.

The other important detail is naming. Commands should model business intent, not storage mutations. Microsoft’s example contrasts “Book hotel room” with “Set ReservationStatus to Reserved”, and Three Dots Labs recommend names close to the way domain experts speak, such as “ScheduleTraining” or “CancelTraining” rather than generic “Create” and “Delete” verbs. In Go, that naming discipline pays off because command names often become type names, handler names, and package boundaries.

Why Teams Reach for It

CQRS becomes attractive when a single CRUD model starts doing too many jobs badly. Microsoft’s guidance lists the usual pressure points: the read and write representations of the same data diverge, concurrent updates create lock contention, read performance suffers under query complexity, and shared entities turn security rules into a tangle. In other words, the problem is not that CRUD is morally wrong. The problem is that one model is being forced to satisfy incompatible concerns at once.

That is especially common in technical products. Writes tend to care about validation, invariants, transactions, and business rules. Reads tend to care about filters, joins, aggregation, caching, sorting, and serving exactly the shape a page or API needs. CQRS lets the write side stay strict and domain-oriented while the read side stays pragmatic and DTO-oriented. Microsoft explicitly recommends a write model focused on validation and consistency, and a read model focused on DTOs or projections optimised for presentation and responsiveness.

There is also a team-level benefit. Three Dots Labs argue that splitting commands and queries improves decoupling, makes execution flow clearer, and speeds up onboarding because developers can inspect a small list of available commands and queries rather than chase logic through random service layers. Microsoft similarly notes CQRS is especially useful in collaborative environments where multiple users update the same data and commands need enough granularity to prevent or resolve conflicts.

My slightly opinionated take is this: most teams adopt CQRS too late, after one “service” has already turned into a soft-centred monolith. But plenty of teams also adopt it too early, mostly because the architecture diagram looked expensive and therefore serious. The right moment is when reads and writes are clearly drifting apart in shape, speed, or rules, not when your todo app has aspirations.

The Benefits and the Bill

Basic CQRS has real benefits even before you add any messaging or separate stores. It gives you smaller command models, smaller query models, clearer use cases, and more obvious places to apply cross-cutting concerns like logging and instrumentation. Three Dots Labs explicitly call out better code organisation, decoupling, and simpler models as immediate wins, while Microservices.io highlights simpler command and query models and support for denormalised, scalable read views.

Once the problem justifies it, CQRS also opens the door to stronger read-side optimisation. Microsoft’s guidance notes that separate read models can use DTOs, projections, read-only replicas, or even a different storage technology entirely. It also points to materialised views as a way to avoid heavy joins and ORM-heavy query paths. If you are evaluating which data access layer to use on the write side, Comparing Go ORMs for PostgreSQL covers the trade-offs between GORM, Ent, Bun, and sqlc in practical terms. That is where CQRS starts paying off operationally, not just structurally.

The cost is equally real. Fowler’s warning is still the right starting point: for most systems CQRS adds risky complexity. Microsoft lists increased complexity and eventual consistency as core considerations, while Microservices.io adds potential code duplication and replication lag in read views. If you split stores, you also inherit the job of keeping them in sync, usually through events, without relying on a tidy distributed transaction between your database and broker.

Event sourcing does not remove that bill; it changes the shape of it. Microsoft’s CQRS guidance says event sourcing can make the event store the single source of truth and let you rebuild materialised views by replaying history, while Event Horizon points to traceability and audit logging as major benefits. But Microsoft also warns that view generation, replay, and event handling add more design complexity, and suggests snapshots to reduce replay costs. That is why I prefer to explain event sourcing as “CQRS plus a second difficult decision”, not as the entry ticket.

A useful rule of thumb worth keeping in mind is that basic CQRS is cheap while distributed CQRS is expensive, and conflating the two conversations is one of the most common ways teams end up with far more complexity than the problem ever required.

A Simple CQRS Implementation in Go

A sensible first step in Go is to keep one database and split only the application layer. Commands own business rules and persistence. Queries return read models shaped for callers. This is exactly the sort of basic CQRS that Three Dots Labs recommend before reaching for asynchronous buses or separate read stores.

Start with commands

package blog

import (
	"context"
	"errors"
	"time"
)

type PublishPostCommand struct {
	Title   string
	Slug    string
	BodyMD  string
	Author  string
}

type PostRepository interface {
	NextID(ctx context.Context) (string, error)
	Save(ctx context.Context, post Post) error
}

type Post struct {
	ID          string
	Title       string
	Slug        string
	BodyMD      string
	Author      string
	PublishedAt time.Time
}

type PublishPostHandler struct {
	Repo  PostRepository
	Now   func() time.Time
}

func (h PublishPostHandler) Handle(ctx context.Context, cmd PublishPostCommand) error {
	if cmd.Title == "" || cmd.Slug == "" || cmd.BodyMD == "" {
		return errors.New("title, slug, and body are required")
	}

	id, err := h.Repo.NextID(ctx)
	if err != nil {
		return err
	}

	post := Post{
		ID:          id,
		Title:       cmd.Title,
		Slug:        cmd.Slug,
		BodyMD:      cmd.BodyMD,
		Author:      cmd.Author,
		PublishedAt: h.Now(),
	}

	return h.Repo.Save(ctx, post)
}

This handler does not try to serve a page, shape a list response, or optimise SQL for a card grid. It just enforces intent and persists a valid aggregate. That is the command side doing one job well.

Add queries

package blog

import "context"

type PostView struct {
	ID          string
	Title       string
	Slug        string
	Author      string
	PublishedAt string
	Excerpt     string
}

type LatestPostsQuery struct {
	Limit int
}

type PostReadModel interface {
	Latest(ctx context.Context, limit int) ([]PostView, error)
	BySlug(ctx context.Context, slug string) (PostView, error)
}

type LatestPostsHandler struct {
	ReadModel PostReadModel
}

func (h LatestPostsHandler) Handle(ctx context.Context, q LatestPostsQuery) ([]PostView, error) {
	limit := q.Limit
	if limit <= 0 {
		limit = 10
	}
	return h.ReadModel.Latest(ctx, limit)
}

type GetPostBySlugQuery struct {
	Slug string
}

type GetPostBySlugHandler struct {
	ReadModel PostReadModel
}

func (h GetPostBySlugHandler) Handle(ctx context.Context, q GetPostBySlugQuery) (PostView, error) {
	return h.ReadModel.BySlug(ctx, q.Slug)
}

Notice the read side returns a PostView, not the write model. That mirrors Microsoft’s recommendation that the read model be optimised for DTOs and presentation, while the write model is tuned for transactional integrity and domain rules.

Wire it like a Go application, not a shrine

package app

import "your/module/internal/blog"

type Application struct {
	Commands Commands
	Queries  Queries
}

type Commands struct {
	PublishPost blog.PublishPostHandler
}

type Queries struct {
	LatestPosts   blog.LatestPostsHandler
	GetPostBySlug blog.GetPostBySlugHandler
}

That shape is not accidental. Three Dots Labs use a very similar pattern in Wild Workouts: an Application type exposing Commands and Queries, with concrete handlers wired from separate app/command and app/query packages. Their service composition code imports those packages separately and constructs a single application object from them. It is a clean, Go-ish way to make the boundary obvious without Framework Drama. If your dependency graph grows complex as handlers multiply, Dependency Injection in Go covers Wire, Dig, and constructor injection patterns that compose naturally with this handler-based structure.

If you later need asynchronous commands, cross-service events, or a denormalised search index, you can add them from this baseline. Three Dots Labs explicitly present asynchronous command buses and separate query databases as later optimisations, not the starting point.

Go Libraries Worth Knowing

The Go CQRS ecosystem is narrower than the .NET one, which is honestly a blessing. You can survey the real options in an afternoon and avoid adopting three abstractions you do not need.

Watermill

Watermill is the clearest modern choice when you want CQRS plus messaging. Its CQRS component is a high-level API that lets you work with Go structs rather than raw messages, and its building blocks include an EventBus, EventProcessor, CommandBus, and CommandProcessor. The docs also cover event handler groups for ordered processing on shared topics, a read-model example, and custom marshaling metadata. Outside the CQRS layer, Watermill supports a wide range of pub/sub back ends including RabbitMQ, Kafka, NATS Jetstream, Redis Streams, Google Cloud Pub/Sub, SQL, HTTP, and others. Pkg.go.dev marks Watermill as production-ready with a stable public API since v1.0.0, and the current published module version is v1.5.2, with GitHub listing that release on 13 May.

commandBus, err := cqrs.NewCommandBusWithConfig(pub, cfg)
eventBus, err := cqrs.NewEventBusWithConfig(pub, cfg)
commandProcessor, err := cqrs.NewCommandProcessorWithConfig(router, cfg)
eventProcessor, err := cqrs.NewEventProcessorWithConfig(router, cfg)

Use Watermill when commands and events need to cross process boundaries, when you want retries and redelivery semantics to be first-class, or when you know your “simple” service is already halfway to event-driven reality. The downside is that you are now having broker, topic, ordering, and idempotency conversations whether you wanted to or not. That is not a flaw in Watermill. That is the cost of the problem space.

Event Horizon

Event Horizon is a CQRS and event sourcing toolkit for Go. Its maintainers describe it as used in production systems, but also note that the API is not final. The toolkit provides aggregate, command, and event registration helpers, official event store implementations for memory and MongoDB variants, projection and repository support, and examples that include an outbox-pattern based application. The release stream is still active, with GitHub showing v0.17.0 on 16 June and earlier releases adding features such as snapshots, retryable projections, persistent command scheduling, and the outbox pattern.

eh.RegisterAggregate(func(id uuid.UUID) eh.Aggregate {
	return &InvoiceAggregate{ID: id}
})

eh.RegisterCommand(func() eh.Command {
	return &CreateInvoiceCommand{}
})

Event Horizon makes the most sense when event sourcing is the point, not an optional future extension. If you want audit-friendly streams, replayable history, projections, and an event-store centric model, it is a serious option. If you only want cleaner application services in a monolith, it is probably more machinery than you need. The “API is not final” note also means you should budget for a little more adaptation over time than you would with Watermill.

Go-MediatR

Go-MediatR is not a full CQRS framework, but it is useful for in-process CQRS. Its README describes it as a mediator pattern implementation used with CQRS, with request/response dispatch for commands and queries, notification dispatch for events, and pipeline behaviours for cross-cutting concerns. The project also has tagged releases, with GitHub listing v1.4.0 as the latest release and calling out thread-safe handler registration and concurrency-related improvements.

resp, err := mediatr.Send[*CreateProductCommand, *CreateProductResponse](ctx, cmd)
post, err := mediatr.Send[*GetPostBySlugQuery, *PostView](ctx, query)

This is a good fit if you want handler-based commands and queries, but not a broker, projection engine, or event store. It is especially friendly for teams coming from MediatR in .NET. The trade-off is equally clear: you still have to design your own persistence, read-model refresh strategy, and out-of-process integration story. In other words, it gives you the application boundary, not the whole architecture.

Older frameworks and reference material

There are older Go CQRS libraries that are still instructive, but I would treat them as reference material before I treated them as greenfield defaults.

jetbasrawi/go.cqrs describes itself as a Go CQRS reference implementation with sample applications based on Greg Young’s principles. However, pkg.go.dev shows no valid go.mod, no tagged version, and no stable version, while GitHub shows no releases and the package metadata was published 7.4 years ago. That is useful history, not a strong signal for a fresh production adoption in 2026.

andrewwebber/cqrs is similar: it provides event sourcing, command issuing and processing, event publishing, and read-model generation from published events, but the package metadata was also published 7.4 years ago. I would absolutely read it if you want to understand how earlier Go CQRS libraries approached the problem. I would be cautious about making it the foundation of a new codebase unless you are happy becoming part-time maintainer of your own architecture stack.

A Practical Go Project Layout

A typical Go CQRS layout should make use cases obvious, not bury them under generic abstractions. Wild Workouts is a good reference here. The repository separates bounded contexts under internal, keeps commands and queries in distinct application packages, and wires them into an Application type exposing Commands and Queries. Service composition pulls together adapters, handlers, and dependencies explicitly. The patterns described here align with the broader guidance in Go Project Structure: Practices & Patterns, which covers the wider set of layout decisions teams face as Go codebases grow.

A pragmatic layout looks like this:

internal/
  blog/
    app/
      app.go
      command/
        publish_post.go
        unpublish_post.go
      query/
        get_post_by_slug.go
        latest_posts.go
    domain/
      post.go
      slug.go
    adapters/
      postgres/
        post_repository.go
        post_read_model.go
    ports/
      http/
        handler.go
    service/
      application.go

This layout has a few advantages.

First, command and query handlers live close to the use cases they implement. That makes it harder to hide business behaviour in repositories or handlers named after transport layers. Three Dots Labs do this directly in Wild Workouts, where app/command and app/query are separate packages and the top-level Application groups handlers by responsibility.

Second, the domain package can stay focused on invariants and behaviour, while the query side is free to return DTOs and projections. That aligns with Microsoft’s write-model and read-model guidance and avoids the common CQRS anti-pattern where the query side is forced back through domain objects just for ideological purity.

Third, this structure scales from the smallest useful CQRS to heavier variants. You can keep one PostgreSQL database and two repository implementations today, then add a search index or event-driven read projection later without having to rewrite the entire application shape. Three Dots Labs explicitly describe that progression from basic CQRS to asynchronous command buses and separate query stores only when the system needs them.

When CQRS Fits and When It Does Not

CQRS makes sense when reads and writes are truly different problems. Microsoft recommends it for workloads where read and write models need independent optimisation, where multiple users collaborate on the same data, and where clear separation helps with performance, scalability, and security. Microservices.io adds another classic fit: denormalised, high-performance views built from domain events or materialised projections. Three Dots Labs also point to complex business logic, maintainability, and future extension toward asynchronous commands or specialised read stores as strong reasons to adopt it in Go.

In practice, that often means systems with rich domain rules, expensive read models, reporting views that do not map neatly to aggregates, or microservices that publish events and build projections elsewhere. In those contexts, the Saga pattern for distributed transactions often appears alongside CQRS as the coordination mechanism for multi-step business operations that span service boundaries. It also fits products where the write side must be strict and auditable while the read side must be fast and shaped for UI or API consumption. If you are already talking about projections, replicas, or rebuilding views from events, you are probably in CQRS territory whether you use the label or not.

CQRS does not make sense when your service is a straightforward data editor. Fowler says outright that for most systems CQRS adds risky complexity, and Three Dots Labs say simple CRUD services that receive and return essentially the same data are not a good fit. In their own Wild Workouts example, a simpler users service does not use Clean Architecture and CQRS because the patterns would not pay their rent there.

That is the part worth saying plainly in a technical blog: CQRS is not a maturity badge but a deliberate trade, and it only makes sense when you actually need what it gives you. If your admin panel writes rows and reads the same rows back, do not separate the model just because you can. If your command handlers are mostly “set field X on record Y”, you do not have a CQRS problem. You have a normal application, and that is perfectly respectable software.

Closing Thoughts

The best way to implement CQRS in Go is to start with the boring version. Split command handlers from query handlers. Let commands model business intent. Let queries return read models. Keep the same database if that is all you need. Then, only when the system forces your hand, add asynchronous buses, projections, separate stores, or event sourcing. That progression is consistent with Fowler’s warning about complexity, Microsoft’s staged CQRS guidance, and the pragmatic Go examples from Three Dots Labs.

If you need a library, Watermill is the strongest general-purpose choice for message-driven CQRS in Go, Event Horizon is compelling when event sourcing is the centre of gravity, and Go-MediatR is a good light touch when you only need in-process command and query dispatch. Everything else should earn its place very carefully. For a broader map of code structure, integration, and data access patterns in production Go systems, the App Architecture guide is a useful companion.

That, in the end, is the most Go-like answer to CQRS: use the pattern, not the costume.