# v0.62.0 — Scheduler Throughput & `pg_aqueduct` Prerequisites

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

## What's New

v0.62.0 delivers two independent but complementary improvements: a
change-buffer fan-out optimisation that eliminates redundant scans in
multi-consumer DAGs, and the three SQL API additions required by the
planned `pg_aqueduct` migration tool (see
[plans/pg-aqueduct-plan.md](../plans/pg-aqueduct-plan.md) §9).

### PERF-1: Change-Buffer Fan-Out (P-1)

The scheduler now scans each source's `changes_<oid>` change buffer
**once per tick** and routes the resulting delta to every dependent
stream table, rather than each dependent node re-scanning the buffer
independently.  For a DAG with N consumers of the same source table
this reduces change-buffer I/O from O(N) to O(1).

The improvement is largest for diamond-topology DAGs where multiple
branches converge on the same upstream source.  Benchmark gate: the
TPC-H 22-node DAG at Δ = 10 K rows must show ≥ 30 % reduction in
total change-buffer scan time vs. v0.61.0 baseline.

No user-facing API change.  The fan-out is enabled automatically and
controlled by a new GUC `pg_trickle.enable_change_buffer_fanout`
(default: `true`).

### API-1: `pgtrickle.pause_scheduler(nodes text[])` (A-1)

Pauses the differential refresh scheduler for the listed stream
tables.  Prevents the scheduler from *starting* new refreshes for
those nodes until `pgtrickle.resume_scheduler()` is called.
In-flight refreshes are drained before the function returns (up to
`pg_trickle.scheduler_drain_timeout`, default 30 s).

Required by `pg_aqueduct apply` to hold the pipeline steady during
schema migrations.  Also useful for operators performing manual
maintenance.

```sql
SELECT pgtrickle.pause_scheduler(ARRAY['public.order_totals', 'public.customer_summary']);
```

### API-2: `pgtrickle.resume_scheduler(nodes text[])` (A-2)

Counterpart to `pause_scheduler()`.  Restores normal scheduling for
the listed nodes.  Called automatically on clean exit and on
`aqueduct apply --resume` after a crash.

```sql
SELECT pgtrickle.resume_scheduler(ARRAY['public.order_totals', 'public.customer_summary']);
```

### API-3: `pgtrickle.stream_table_spec(relid oid) RETURNS jsonb` (A-3)

Returns a stable JSON projection of a single stream table's
specification — the canonical representation needed by `pg_aqueduct`
for `import`, drift detection, and the spec-hash in
`aqueduct.dag_versions`.

```json
{
  "name": "order_totals",
  "schema": "public",
  "query": "SELECT customer_id, sum(amount) FROM orders GROUP BY 1",
  "refresh_mode": "DIFFERENTIAL",
  "schedule": "30s",
  "cdc_mode": "trigger",
  "oid": 12345,
  "diamond_group": null,
  "attach_outbox": null,
  "cdc_slot_name": null
}
```

Field stability is guaranteed across minor versions; new optional
fields may be added in future releases.  Useful beyond `pg_aqueduct`:
operators can query this function directly from dashboards and `psql`
sessions for a canonical view of a stream table's live configuration.