# v0.29.0 — Relay CLI (`pgtrickle-relay`)

> **Full technical details:** [v0.29.0.md-full.md](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:

```sql
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](v0.28.0.md)*
*Next: [v0.30.0 — Pre-GA Correctness & Stability Sprint](v0.30.0.md)*