# go-sequent

> go-sequent is a Go library for CQRS and event sourcing, built for financial ledgers, payments and wallets. It runs inside your own service on PostgreSQL. It is a pure library with no HTTP server.

- Module: github.com/go-sequent/go-sequent
- Site: https://go-sequent.org
- Source: https://github.com/go-sequent/go-sequent
- License: MIT
- Languages: English, 中文

Locked defaults:

- Ledger projections run SyncInTxn, in the same transaction as the events.
- Money is `types.Money` (decimal). `float64` money is banned.
- Integrity is a per-aggregate hash chain. There are no event signatures.
- Tenancy is a shared schema with `tenant_id`.
- GDPR erasure is by tombstone only.
- The outbox is a PostgreSQL table drained by polling.
- go-sequent never imports a Ruby Sequent database.

## Start here

- [go-sequent documentation](https://go-sequent.org/docs): Documentation for go-sequent, a Go library for CQRS and event sourcing built for ledgers and payments. Start here to find guides, API reference, operations runbooks and security notes.
- [Getting started](https://go-sequent.org/docs/getting-started): Install go-sequent, run the bank example against the in-memory store, and execute your first commands with SyncInTxn balance projections, idempotency and tenancy.
- [What is go-sequent](https://go-sequent.org/docs/what-is-go-sequent): A Go CQRS + Event Sourcing library for financial ledgers with SyncInTxn projections and hash-chain integrity.
- [Core loop](https://go-sequent.org/docs/core-loop): The go-sequent write path step by step: CommandService.Execute, middleware, AuthZ filters, handlers, Repository.Commit, SyncInTxn publish, transaction commit and AfterCommit hooks.

## Guides

- [Modelling the domain](https://go-sequent.org/docs/modelling-the-domain): A step-by-step go-sequent tutorial using the bank Account: events, commands, the aggregate with appliers and invariants, a handler, a SyncInTxn balance projector and wiring.
- [Write-path consistency](https://go-sequent.org/docs/write-path-consistency): How UnitOfWork, optimistic concurrency control and idempotency work together in go-sequent. What each layer protects against, what it does not, and how to wire and handle them.
- [Bank example](https://go-sequent.org/docs/bank-example): A tour of go-sequent's two bank samples: the in-memory demo in examples/bank and the Postgres-backed examples/bankpg with SQL balances, tenancy, idempotency and AuthZ.

## Reference

- [Command](https://go-sequent.org/docs/command): Reference for go-sequent's Command interface and Meta: command types, aggregate ids, tenant and idempotency fields, audit snapshots with AuditOf, and Validate hooks.
- [Event](https://go-sequent.org/docs/event): Reference for go-sequent events: the Event interface, event.Base envelope, the type Registry for JSON decoding, naming rules, and where upcasters fit.
- [AggregateRoot](https://go-sequent.org/docs/aggregate-root): Reference for go-sequent aggregates: the Root interface, embedding aggregate.Base, pure appliers, Apply, invariants, unique keys, partition keys and uncommitted events.
- [CommandHandler](https://go-sequent.org/docs/command-handler): Reference for go-sequent command handlers: the Handler interface, Router registration, repository-only access, multi-aggregate commands such as transfers, and duplicate-type panics.
- [Repository and UnitOfWork](https://go-sequent.org/docs/repository): Reference for go-sequent's aggregate Repository and context-scoped UnitOfWork: Add, Load, Commit, identity map behaviour, factories, snapshot loading and goroutine rules.
- [CommandService](https://go-sequent.org/docs/command-service): Reference for go-sequent's command.Service: Execute semantics, middleware order, filters, validation, the command queue, AfterCommit hooks, and how Obs attaches.
- [EventStore](https://go-sequent.org/docs/event-store): Reference for go-sequent's EventStore: the Store interface, memory and Postgres backends, errors, per-aggregate SHA-256 hash chain with canonical input, and verification.
- [Publisher and SyncInTxn](https://go-sequent.org/docs/publisher): Reference for go-sequent publishing: SyncInTxn runs projectors and workflows inside the write transaction, PublishProjectorsOnly for replay, and WithOutbox with Postgres table polling.
- [Projector](https://go-sequent.org/docs/projector): Reference for go-sequent projectors: the Projector interface with ManagedTables, SyncInTxn balance projections, the Persistor for replay-safe SQL, EventRouter, and rebuild rules.
- [Workflow](https://go-sequent.org/docs/workflow): Reference for go-sequent workflows and AfterCommit hooks: reacting to events inside the transaction, running side effects only after commit, and exclusion from projection rebuild.
- [Snapshotting](https://go-sequent.org/docs/snapshotting): Reference for go-sequent JSON snapshots: implementing SnapshotVersion, MarshalSnapshot and UnmarshalSnapshot, how the repository loads snapshots, the background Snapshotter, and versioning.
- [Unique keys and OCC](https://go-sequent.org/docs/unique-keys-occ): Reference for go-sequent optimistic concurrency control and aggregate unique keys: ExpectedVersion, ErrOptimisticConcurrency, tenant-scoped UniqueKeys scopes and ErrUniqueKeyViolation.
- [Idempotency](https://go-sequent.org/docs/idempotency): Reference for go-sequent's tenant-scoped idempotency: the (TenantID, IdempotencyKey) key space, memory and Postgres stores, default no-op replay, Strict mode with ErrReplay, and wiring order.
- [AuthZ](https://go-sequent.org/docs/authz): Reference for go-sequent authorization at the command boundary: security.Authorizer, AllowAll, DenyByDefault, WithAuthorizer filters, Middleware, ErrDenied and the AuthContext trust model.
- [Tenancy](https://go-sequent.org/docs/tenancy): Reference for go-sequent multi-tenancy: shared schema with tenant_id, tenancy.WithTenant and Middleware, UniqueScope, partition keys, and a Circle multi-merchant mapping example.
- [Money](https://go-sequent.org/docs/money): Reference for go-sequent's types.Money: decimal amounts with ISO currency codes, JSON string encoding, arithmetic, rounding, and the float64 ban with AssertNoFloatMoney and BanFloat64Money.
- [OpenTelemetry](https://go-sequent.org/docs/opentelemetry): Reference for go-sequent's optional obs package: spans and metrics for command latency, success and error counts, optimistic-concurrency conflicts and outbox depth, plus provider setup and limits.
- [Migrations and CLI](https://go-sequent.org/docs/migrations-cli): Reference for go-sequent schema migrations and the ops CLI: store.Migrate, the migrate, replay and outbox commands with their flags, and what the CLI leaves to your application binary.
- [Wiring the façade](https://go-sequent.org/docs/wiring): How to assemble a go-sequent application with the sequent package: sequent.New, options such as WithStore, WithIdempotency, WithAuthorizer and WithObs, Register methods, and middleware order.
- [Testing](https://go-sequent.org/docs/testing): How to test go-sequent applications: testkit Given/When/Expect for aggregates, memory-store integration tests, OCC and idempotency cases, Postgres tests via GO_SEQUENT_PG_DSN, and benchmarks.
- [Glossary](https://go-sequent.org/docs/glossary): Definitions of go-sequent terms: ledger projection, SyncInTxn, aggregate, command, event, event store, hash chain, UnitOfWork, OCC, idempotency, tenant, outbox, snapshot, tombstone and more.
- [Locked decisions](https://go-sequent.org/docs/decisions): The design decisions that fix go-sequent's behaviour: SyncInTxn ledger projections, decimal money, hash-chain integrity, shared-schema tenancy, tombstone GDPR, Postgres outbox, pure library and MIT licensing.
- [go-sequent vs Sequent (Ruby)](https://go-sequent.org/docs/vs-sequent-ruby): How go-sequent relates to Ruby's Sequent: concept mapping, what is implemented in Go, what differs (context-scoped UnitOfWork, decimal money, hash chain) and what is deliberately not ported.

## Operations

- [Operations overview](https://go-sequent.org/docs/ops): Production runbooks for go-sequent on PostgreSQL: failover, projection rebuild, backup and restore, and partitioning, with the locked defaults they all assume.
- [PostgreSQL failover runbook](https://go-sequent.org/docs/failover): Keep a single writer for the go-sequent event store through a PostgreSQL failover: routing rules, a six-step checklist, application guidance and what the library does not do.
- [Projection rebuild runbook](https://go-sequent.org/docs/projection-rebuild): Rebuild disposable read models with the go-sequent replay pipeline: prepare, replay, catchup, optimize and golive, with the library API, CLI schema stages and operational tips.
- [Backup and restore runbook](https://go-sequent.org/docs/backup-restore): Back up the go-sequent PostgreSQL event store and rehearse a verified restore: what to protect, continuous WAL archiving, a quarterly drill, point-in-time recovery and snapshots after restore.
- [Partitioning guidance](https://go-sequent.org/docs/partitioning): When and how to partition the go-sequent event store inside the shared-schema, tenant_id model: partition_key, triggers, recommended steps, optional RLS and the example SQL.

## Security

- [Threat model](https://go-sequent.org/docs/threat-model): The go-sequent threat model: assets, trust boundaries, threats with mitigations, explicit non-goals, and a review checklist for applications built on the library.
- [Event evolution](https://go-sequent.org/docs/event-evolution): Compatibility policy for changing go-sequent events over time: upcaster rules, versioning strategies, a compatibility matrix, forbidden practices and test expectations.

## 中文文档

### 入门

- [go-sequent 文档](https://go-sequent.org/zh/docs): go-sequent 是面向账本与支付的 Go CQRS + Event Sourcing 库。汇总入门、指南、API 参考、运维手册与安全说明。
- [快速开始](https://go-sequent.org/zh/docs/getting-started): 安装 go-sequent，用内存 EventStore 跑通 bank 示例，体验 SyncInTxn 余额读模型、Idempotency 与 Tenancy（多租户）。
- [go-sequent 是什么](https://go-sequent.org/zh/docs/what-is-go-sequent): 面向支付与账本的 Go CQRS + Event Sourcing 库：SyncInTxn 读模型、OCC、decimal Money、hash chain、Tenancy（多租户）。
- [核心闭环](https://go-sequent.org/zh/docs/core-loop): go-sequent 写路径逐步说明：CommandService.Execute、中间件、AuthZ、Handler、Repository.Commit、SyncInTxn 发布、事务提交与 AfterCommit。

### 指南

- [领域建模](https://go-sequent.org/zh/docs/modelling-the-domain): 以 bank Account 为例的 go-sequent 分步教程：Event、Command、带 applier 与不变量的 Aggregate、Handler、SyncInTxn 余额 Projector，以及接线运行。
- [写路径一致性](https://go-sequent.org/zh/docs/write-path-consistency): UnitOfWork、OCC（用 ExpectedVersion 防并发写冲突）与 Idempotency（同一业务键重复提交只生效一次）如何配合。
- [Bank 示例](https://go-sequent.org/zh/docs/bank-example): go-sequent 两个 bank 示例导览：examples/bank 内存演示，以及 examples/bankpg 的 Postgres 版本（SQL 余额、Tenancy、Idempotency 与 AuthZ）。

### 参考

- [Command](https://go-sequent.org/zh/docs/command): go-sequent 的 Command 接口与 Meta 参考：命令类型、聚合 id、租户与 Idempotency 字段、用 AuditOf 生成审计快照，以及 Validate 钩子。
- [Event](https://go-sequent.org/zh/docs/event): go-sequent 事件参考：Event 接口、event.Base 信封、用于 JSON 解码的类型 Registry、命名规则，以及 upcaster 的位置。
- [AggregateRoot](https://go-sequent.org/zh/docs/aggregate-root): go-sequent 聚合参考：Root 接口、嵌入 aggregate.Base、纯状态 applier、Apply、不变量、唯一键、分区键与未提交事件。
- [CommandHandler](https://go-sequent.org/zh/docs/command-handler): go-sequent 命令处理器参考：Handler 接口、Router 注册、仅通过 Repository 访问聚合、转账等多聚合命令，以及重复类型注册会 panic。
- [Repository 与 UnitOfWork](https://go-sequent.org/zh/docs/repository): go-sequent 聚合 Repository 与 context 级 UnitOfWork 参考：Add、Load、Commit、identity map 行为、工厂注册、快照加载与 goroutine 使用规则。
- [CommandService](https://go-sequent.org/zh/docs/command-service): go-sequent command.Service 参考：Execute 语义、中间件顺序、过滤器、校验、命令队列、AfterCommit 钩子，以及 Obs 如何挂接。
- [EventStore](https://go-sequent.org/zh/docs/event-store): go-sequent EventStore 参考：Store 接口、memory 与 Postgres 后端、错误类型、按聚合的 SHA-256 hash chain 及其规范输入与校验。
- [Publisher 与 SyncInTxn](https://go-sequent.org/zh/docs/publisher): go-sequent 发布机制：SyncInTxn 在写事务里同步更新读模型，重建用 PublishProjectorsOnly，以及 Postgres 表轮询的 WithOutbox。
- [Projector](https://go-sequent.org/zh/docs/projector): go-sequent Projector 参考：ManagedTables、SyncInTxn 余额读模型、可重放的 SQL Persistor、EventRouter 与重建规则。
- [Workflow](https://go-sequent.org/zh/docs/workflow): go-sequent Workflow 与 AfterCommit 钩子参考：在事务内响应事件、只在提交之后执行副作用，以及不参与读模型重建。
- [Snapshotting](https://go-sequent.org/zh/docs/snapshotting): go-sequent JSON 快照参考：实现 SnapshotVersion、MarshalSnapshot 与 UnmarshalSnapshot，Repository 如何加载快照，后台 Snapshotter，以及版本管理。
- [唯一键与 OCC](https://go-sequent.org/zh/docs/unique-keys-occ): go-sequent 乐观并发控制与聚合唯一键参考：ExpectedVersion、ErrOptimisticConcurrency、带租户前缀的 UniqueKeys scope 以及 ErrUniqueKeyViolation。
- [Idempotency](https://go-sequent.org/zh/docs/idempotency): go-sequent 租户级 Idempotency 参考：(TenantID, IdempotencyKey) 键空间、memory 与 Postgres 存储、默认的空操作重放、Strict 模式的 ErrReplay，以及接线顺序。
- [AuthZ](https://go-sequent.org/zh/docs/authz): go-sequent 命令边界授权参考：security.Authorizer、AllowAll、DenyByDefault、WithAuthorizer 过滤器、Middleware、ErrDenied 与 AuthContext 信任模型。
- [Tenancy（多租户）](https://go-sequent.org/zh/docs/tenancy): go-sequent Tenancy 参考：共享 schema + tenant_id、tenancy.WithTenant 与 Middleware、UniqueScope、分区键，以及 Circle 多商户映射示例。
- [Money](https://go-sequent.org/zh/docs/money): go-sequent types.Money 参考：带 ISO 币种的 decimal 金额、JSON 字符串编码、四则运算与舍入，以及用 AssertNoFloatMoney 和 BanFloat64Money 禁用 float64。
- [OpenTelemetry](https://go-sequent.org/zh/docs/opentelemetry): go-sequent 可选 obs 包参考：命令延迟、成功/失败计数、乐观并发冲突与 outbox 积压的 span 和指标，以及 Provider 配置与限制。
- [Migrations 与 CLI](https://go-sequent.org/zh/docs/migrations-cli): go-sequent 的 schema 迁移与运维 CLI 参考：store.Migrate、migrate / replay / outbox 命令及参数，以及 CLI 留给应用二进制的部分。
- [sequent 门面接线](https://go-sequent.org/zh/docs/wiring): 如何用 sequent 包装配 go-sequent 应用：sequent.New、WithStore / WithIdempotency / WithAuthorizer / WithObs 选项、Register 方法与中间件顺序。
- [测试](https://go-sequent.org/zh/docs/testing): 如何测试 go-sequent 应用：用 testkit 做聚合 Given/When/Expect、内存 store 集成测试、OCC 与 Idempotency 用例、通过 GO_SEQUENT_PG_DSN 运行 Postgres 测试，以及基准测试。
- [名词释义](https://go-sequent.org/zh/docs/glossary): go-sequent 术语：Projector、SyncInTxn、Aggregate、Command、Event、EventStore、hash chain、UnitOfWork、OCC、Idempotency、Tenant、Outbox、Snapshot、Tombstone 等。
- [锁定决策](https://go-sequent.org/zh/docs/decisions): 决定 go-sequent 行为的设计决策：SyncInTxn 账本读模型、decimal Money、hash chain、共享 schema Tenancy、Tombstone GDPR、Postgres Outbox、纯库形态与 MIT 许可。
- [相对 Sequent Ruby](https://go-sequent.org/zh/docs/vs-sequent-ruby): go-sequent 与 Ruby 版 Sequent 的关系：概念映射、Go 中已实现的部分、差异（context 级 UnitOfWork、decimal 金额、hash chain）以及刻意不移植的内容。

### 运维

- [运维概览](https://go-sequent.org/zh/docs/ops): go-sequent 在 PostgreSQL 上的生产运维手册：故障切换、读模型重建、备份恢复与分区，以及它们共同假设的锁定默认值。
- [PostgreSQL 故障切换手册](https://go-sequent.org/zh/docs/failover): 在 PostgreSQL 故障切换期间为 go-sequent 事件库保持单写者：路由规则、六步清单、应用侧建议，以及库不做的事。
- [读模型重建手册](https://go-sequent.org/zh/docs/projection-rebuild): 用 go-sequent 的 replay 流水线重建可丢弃的读模型：prepare、replay、catchup、optimize、golive，含库 API、CLI schema 阶段与运维提示。
- [备份与恢复手册](https://go-sequent.org/zh/docs/backup-restore): 备份 go-sequent 的 PostgreSQL 事件库并演练经过验证的恢复：备份对象、持续 WAL 归档、季度演练、时间点恢复，以及恢复后的快照处理。
- [分区指南](https://go-sequent.org/zh/docs/partitioning): 在共享 schema + tenant_id 模型内，何时以及如何对 go-sequent 事件库做分区：partition_key、触发条件、推荐步骤、可选 RLS 与示例 SQL。

### 安全

- [威胁模型](https://go-sequent.org/zh/docs/threat-model): go-sequent 的威胁模型：资产、信任边界、威胁与缓解措施、明确的非目标，以及基于该库构建应用时的评审清单。
- [事件演进](https://go-sequent.org/zh/docs/event-evolution): 随时间修改 go-sequent 事件的兼容性策略：upcaster 规则、版本化策略、兼容性矩阵、禁止事项与测试要求。

## Optional

- [Full documentation as one file](https://go-sequent.org/llms-full.txt): All English pages concatenated as plain markdown.