# v0.33.0 — Reactive Subscriptions & Zero-Downtime Operations

> **Full technical details:** [v0.33.0.md-full.md](v0.33.0.md-full.md)

**Status: Planned** | **Scope: Medium**

> Live push notifications to applications, and a way to change a stream
> table's defining query on a large production table without downtime.

---

## What is this?

v0.33.0 adds two long-requested operational capabilities:

1. **Push notifications** — applications can subscribe to changes in a
   stream table and receive instant notifications, enabling real-time
   dashboards, live UIs, and event-driven microservices.

2. **Zero-downtime query changes** — modifying the defining query of a
   large stream table no longer requires a multi-minute lock on the table.

---

## Reactive subscriptions

`pgtrickle.subscribe('my_stream_table', 'my_notification_channel')` registers
a listener. After every successful refresh that produces at least one change,
pg_trickle sends a PostgreSQL `NOTIFY` message to the named channel with a
payload like:

```json
{"name": "my_stream_table", "inserted_count": 12, "deleted_count": 3}
```

Any application holding a standard PostgreSQL connection and listening on
that channel receives this signal immediately, without polling. This powers
real-time dashboards, event-driven microservices, and reactive frontends —
using nothing but a standard PostgreSQL driver, with no Kafka, no Debezium,
no Hasura required.

A configurable coalescence window prevents notification storms when a stream
table refreshes at high frequency.

---

## Shadow-ST: zero-downtime query evolution

Today, calling `alter_query()` on a large stream table triggers a full
re-computation of the entire result set. For a stream table with millions of
rows, this can lock the table for minutes — an unacceptable operation in
production.

The new `shadow_build := true` parameter to `alter_query()` changes how
this works:

1. A parallel "shadow" stream table is created from the new query, invisible
   to users.
2. The shadow table is refreshed to convergence in the background, with no
   lock on the live table. The live table continues to serve reads and accept
   writes normally throughout.
3. When the shadow table has caught up, the storage is swapped atomically.
4. The new query goes live at the next refresh cycle. The shadow table is
   dropped.

The live table is readable and writable from start to finish.

---

## Scope

v0.33.0 is a medium-sized release. The shadow-ST feature touches the refresh
orchestrator — the most change-sensitive module in the codebase — and ships
behind a feature flag with a full TPC-H validation pass before the flag is
removed.

---

*Previous: [v0.32.0 — Citus: Stable Naming & Per-Source Frontier Foundation](v0.32.0.md)*
*Next: [v0.34.0 — Temporal IVM & Columnar Materialization](v0.34.0.md)*
