PGCQRS

Provides a JSON event store with support for multi-tenancy and observability.

Features

• Event Storage: Persists all events directly into Postgres.
• Multi-Tenancy: separate streams for each client application or domain.
• Security: Support for TLS.
• Observability: Native OpenTelemetry (OTEL) instrumentation.

Usage

Launch a local development environment via Docker Compose with the following:

./dev.sh up

Example operations in Go

    //Creates the stream
    exampleKind := "example" //used for the kind of event
    stream := sys.MustStream(ctx, "readme", "test")
    //submit events to be queried
    stream.MustSubmit(ctx, exampleKind, &Event{First: true})
    stream.MustSubmit(ctx, exampleKind, &Event{First: false})

    // prepare a query to find all events with First == true
    q := query2.NewQuery(stream)
    q.OnKind(exampleKind).Subset(Event{First: true}).On(v1.EntityFunc(func(ctx context.Context, e v1.Envelope, entity Event) {
        //will be called for each found event as the query is executing
        fmt.Printf("%#v\n", e)
    }))
    if err = q.StreamBatch(ctx); err != nil {
        panic(err)
    }

See the full example in examples/readme/main.go .

Development: Getting started quickly

To get started quickly, you'll need:

• Go 1.25+
• Docker & Docker Compose (for local development)

Just run ./docker-up.sh to get it moving on port 9000 and 9001 . The tool pgcqrs will be available in the root of the repository.

The dev.sh script provides fine-grained control over the development workflow:

# Full pipeline: build, test, deploy, run examples + integration tests
./dev.sh up

# Rebuild and restart containers only (after code changes)
./dev.sh services

# Run example drift detection only
./dev.sh examples

# Run transport verification tests only (memory, HTTP, gRPC)
./dev.sh integration

# Run both examples + integration tests
./dev.sh system_tests

Typical workflow: Make code changes → ./dev.sh services → ./dev.sh examples or ./dev.sh integration as needed.

Examples and Testing

The project contains several examples demonstrating different usage patterns in the examples/ directory:

• Simple: Basic usage (examples/simple)
• Querying: How to query events (examples/query, examples/query2)
• Watching: Subscribing to streams (examples/watch)
• Batching: Batch query operations (examples/queryBatch)
• View Projections: Materialized views with typed handlers (examples/view-projection, examples/view-projection-versioned, examples/view-projection-watch) - requires gRPC transport

A whole battery of examples are available via ./run-examples.sh or ./dev.sh examples.

Contributing

Pull requests are welcome.

For major changes, please open an issue first to discuss what you would like to change.

Contributions will be accepted under the Apache 2.0 license.