Skip to content
go-sequentCQRS + Event Sourcing for Go financial systems

Reference

Migrations and 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.

Migrations and CLI

go-sequent has two things to migrate: the event store schema, and projection tables (read models). The first is a set of versioned SQL steps. The second is a rebuild pipeline.

Event store schema

Store.Migrate on the Postgres store applies the schema steps in order:

Step File
1 001_phase1.sql
2 002_phase2.sql
3 003_store_events.sql
4 004_phase3.sql
5 005_hash_chain.sql
6 006_event_json_bytea.sql 
store, err := postgres.Open(ctx, dsn, app.Events)
if err != nil { /* ... */ }
if err := store.Migrate(ctx); err != nil { /* ... */ }

Migrate is safe to run repeatedly and from several processes. It takes a Postgres advisory lock so concurrent callers are serialized, and it records applied steps in go_sequent_schema_migrations. Later runs do nothing.

Run migrations from a deployment step or an init job, not from every application replica at startup, so schema changes are visible in your release process.

Core tables include commands, aggregates, events, the *_types registries, aggregate_unique_keys, snapshot_records, aggregates_that_need_snapshots, idempotency_keys, outbox, event_tombstones and projector_replay_states.

The partitioning SQL under docs/ops/sql/ is example-only. Migrate never applies it. See Partitioning.

The CLI

The CLI lives in cmd/go-sequent. Every command takes -dsn, which defaults to the GO_SEQUENT_PG_DSN environment variable.

go run ./cmd/go-sequent migrate -dsn "$GO_SEQUENT_PG_DSN"
go run ./cmd/go-sequent outbox  -dsn "$DSN" [-once]
go run ./cmd/go-sequent replay  -dsn "$DSN" -projector name -stage prepare -tables t1

Tagged releases publish prebuilt go-sequent binaries for Linux, macOS and Windows on amd64 and arm64.

migrate

Opens the store and runs Migrate. Prints migrate: ok when done.

replay

Runs schema stages of the projection rebuild pipeline.

Flag Default Meaning
-dsn $GO_SEQUENT_PG_DSN Postgres DSN (required)
-projector default Projector name, used as the replay state key
-stage all prepare, optimize, golive, abort (also replay, catchup, all; see below)
-tables empty Comma-separated managed tables
-replay-schema replay_<name> Replay schema name
-view-schema public Live schema that tables are swapped into 
go run ./cmd/go-sequent replay -dsn "$DSN" -projector balances \
  -stage prepare -tables account_balances

The CLI supports prepare, optimize, golive and abort. The stages that stream events, replay and catchup, and all, fail with a message: they need your projectors and an event source, which only your application binary knows. Run those through the replay.Pipeline API from your own program. See Projection rebuild.

outbox

Drains the Postgres outbox by polling.

Flag Default Meaning
-dsn $GO_SEQUENT_PG_DSN Postgres DSN (required)
-once false Process one batch and exit
-interval 1s Poll interval
-batch 10 Claim batch size 
go run ./cmd/go-sequent outbox -dsn "$DSN" -once

The delivery handler in the bundled CLI prints each message. Replace it in your own binary for real delivery. See Publisher.

Projection migrations

Projection tables are not versioned by Migrate. They belong to your application, and you rebuild them from events with the replay pipeline when their shape changes. For the example sample, bankpg.MigrateProjection(ctx, store.Pool) creates its balance table after store.Migrate.

Data from Ruby Sequent

go-sequent never imports a Ruby Sequent database or dump. The schema is Go-native. See vs Sequent (Ruby).

Docs track the go-sequent library. When APIs drift, the source wins.