v0.29.0 — Relay CLI (pgtrickle-relay)

Full technical details: v0.29.0.md-full.md

Status: ✅ Released | Scope: Large (~5 weeks)

A standalone connector that bridges pg_trickle outboxes and inboxes with Kafka, NATS, SQS, webhooks, and more — configured entirely with SQL.

What is this?

v0.28.0 built the mailbox. v0.29.0 builds the postman.

pgtrickle-relay is a standalone command-line tool written in Rust that connects pg_trickle outboxes and inboxes to external messaging systems. Without this tool, users have to write their own relay process from scratch. With it, connecting a pg_trickle stream table to Kafka, NATS, or an SQS queue is a matter of minutes and a few lines of SQL configuration.

Forward mode (outbox → external system)

The relay polls the pg_trickle outbox and publishes each delta to an external sink. Supported sinks at launch:

Sink Notes
NATS JetStream With Nats-Msg-Id deduplication header
Apache Kafka Idempotent producer, SASL/SSL
HTTP webhook Per-event or batched, with Idempotency-Key header
Redis Streams XADD with configurable stream key
Amazon SQS SendMessageBatch, FIFO dedup
Remote PostgreSQL inbox ON CONFLICT deduplication
RabbitMQ AMQP Manual ack/nack
stdout / file JSON-Lines, JSON pretty-print, CSV

Reverse mode (external system → inbox)

The relay also works in reverse: it consumes messages from an external source and writes them into a pg_trickle inbox, with automatic deduplication. The same eight backends are supported as sources.

This enables patterns like: a NATS message arrives, the relay writes it to the pg_trickle inbox, the inbox pending stream table updates, and a database-side processor handles it — all with exactly-once delivery guaranteed by the three-layer deduplication chain (broker ID → inbox ON CONFLICT → outbox idempotency key).

Configuration

All relay pipelines are configured with SQL, not config files. There is no YAML or TOML to maintain. A pipeline is created with:

SELECT pgtrickle.set_relay_outbox('my_pipeline', ...);
SELECT pgtrickle.enable_relay('my_pipeline');

The relay binary picks up changes at runtime via PostgreSQL LISTEN/NOTIFY — no restart needed.

Sub-100 ms latency

The relay wakes up instantly when new outbox rows are written, thanks to the pg_notify signal emitted by the outbox (introduced in v0.28.0). Poll intervals become the fallback rather than the primary wake-up mechanism.

Scope

v0.29.0 is a large release — approximately five weeks of engineering effort. It ships as a separate binary alongside pg_trickle, distributed as a Docker container, Homebrew formula, and pre-built binaries for Linux and macOS on both x86-64 and ARM.

Previous: v0.28.0 — Transactional Inbox & Outbox Patterns Next: v0.30.0 — Pre-GA Correctness & Stability Sprint