README
¶
go-mink Examples
Sixteen self-contained, runnable programs that show every major go-mink feature in action. Each lives in its own folder with a dedicated README explaining what it does, how to run it, and what to look for.
Most examples need zero infrastructure — just go run. Two use PostgreSQL (marked 🐘) and start it for you via Docker Compose.
Prerequisites
- Go 1.25+
- Docker (only for the 🐘 PostgreSQL examples)
Running an example
# From the repository root:
go run ./examples/basic # in-memory examples — no setup
# bdd-testing is a test suite, run it with `go test`:
go test -v ./examples/bdd-testing
For the PostgreSQL examples, start infra first and stop it after:
docker compose -f docker-compose.test.yml up -d --wait
go run ./examples/cqrs-postgres
docker compose -f docker-compose.test.yml down
The adapter auto-creates its schema on first use, so there's nothing to migrate by hand.
The examples
Start here
| Example | What it shows | Infra |
|---|---|---|
| basic | The fundamentals — define events, model an aggregate, save and replay a stream | — |
| cqrs | Dispatch commands through a bus with a full middleware pipeline | — |
| projections | Turn events into queryable read models (inline & live) | — |
Core patterns
| Example | What it shows | Infra |
|---|---|---|
| sagas | Coordinate multi-step workflows with automatic compensation | — |
| cqrs-postgres | The cqrs example backed by a real PostgreSQL database |
🐘 |
| full-ecommerce | Everything together — a realistic order-fulfillment system | 🐘 |
Schema & serialization
| Example | What it shows | Infra |
|---|---|---|
| versioning | Evolve event schemas (v1 → v2 → v3) with upcasting — no DB migration | — |
| msgpack | Swap in MessagePack serialization for smaller, faster payloads | — |
| protobuf | Strongly-typed, schema-enforced Protocol Buffers serialization | — |
Security, privacy & compliance
| Example | What it shows | Infra |
|---|---|---|
| encryption | Field-level encryption at rest, per-tenant keys, crypto-shredding | — |
| reencrypt-inplace | Backfill encryption onto existing plaintext history in place (idempotent) | — |
| export | GDPR data export (right to access / portability) | — |
| audit | An immutable audit trail of every command (who/what/when/outcome) | — |
Observability & testing
| Example | What it shows | Infra |
|---|---|---|
| metrics | Prometheus metrics for commands and event-store operations | — |
| tracing | OpenTelemetry distributed tracing | — |
| bdd-testing | Behavior-driven aggregate tests with Given/When/Then | — |
| feed-filter | Read the event feed filtered by type / stream / category — for audit & introspection | — |
Suggested learning path
- basic — understand events, aggregates, and the event store.
- cqrs — add commands, handlers, and middleware.
- projections — build read models for queries.
- sagas — orchestrate workflows across aggregates.
- Pick the production concerns you care about — versioning, encryption, export, audit, metrics, tracing, feed-filter.
- full-ecommerce — see how it all composes into one system.
Learn more
- 📖 Documentation: go-mink.dev
- 🎓 Guided tutorial: Build an e-commerce system
- 🔎 API reference: pkg.go.dev/go-mink.dev
- 🏠 Project README: ../README.md
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main demonstrates the command Audit Logging middleware.
|
Package main demonstrates the command Audit Logging middleware. |
|
Package main demonstrates the basic usage of go-mink for event sourcing.
|
Package main demonstrates the basic usage of go-mink for event sourcing. |
|
Package main demonstrates the CQRS and Command Bus features of go-mink (Phase 2).
|
Package main demonstrates the CQRS and Command Bus features of go-mink (Phase 2). |
|
Package main demonstrates Phase 2 CQRS & Command Bus features with PostgreSQL.
|
Package main demonstrates Phase 2 CQRS & Command Bus features with PostgreSQL. |
|
Package main demonstrates field-level encryption in go-mink.
|
Package main demonstrates field-level encryption in go-mink. |
|
Package main demonstrates GDPR data export (right to access / data portability) in go-mink.
|
Package main demonstrates GDPR data export (right to access / data portability) in go-mink. |
|
Package main demonstrates filtered feed reads — reading the global event feed by an INDEXED axis for introspection.
|
Package main demonstrates filtered feed reads — reading the global event feed by an INDEXED axis for introspection. |
|
Package main demonstrates a complete e-commerce order fulfillment system using go-mink.
|
Package main demonstrates a complete e-commerce order fulfillment system using go-mink. |
|
Example: Metrics Middleware
|
Example: Metrics Middleware |
|
Example: MessagePack Serializer
|
Example: MessagePack Serializer |
|
Package main demonstrates the projection and read model features of go-mink.
|
Package main demonstrates the projection and read model features of go-mink. |
|
Example: Protocol Buffers Serializer
|
Example: Protocol Buffers Serializer |
|
Package main demonstrates in-place stream re-encryption — the historical backfill for a store that enabled field encryption AFTER it already had plaintext data.
|
Package main demonstrates in-place stream re-encryption — the historical backfill for a store that enabled field encryption AFTER it already had plaintext data. |
|
Example: Saga (Process Manager) Pattern
|
Example: Saga (Process Manager) Pattern |
|
Example: Distributed Tracing with OpenTelemetry
|
Example: Distributed Tracing with OpenTelemetry |
|
Package main demonstrates event versioning and upcasting in go-mink.
|
Package main demonstrates event versioning and upcasting in go-mink. |
Click to show internal directories.
Click to hide internal directories.