# v0.14.0 — Tiered Scheduling, UNLOGGED Buffers, and a TUI Dashboard

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

**Status: ✅ Released** | **Scope: Medium** (~4 weeks)

> Priority-based tiered scheduling that ensures the most latency-sensitive
> stream tables refresh first, faster change buffers using unlogged tables,
> rich diagnostic output for refresh mode decisions, and an interactive
> terminal dashboard.

---

## What problem does this solve?

In a deployment with many stream tables of varying importance, all tables
were treated equally — a low-priority background summary would compete for
refresh resources with a high-priority user-facing dashboard. Change buffers
were WAL-logged (the PostgreSQL default) even though they are transient data
that does not need to survive a crash. And operators needed a better way to
see what was happening without writing custom queries.

---

## Tiered Scheduling

Stream tables are now assigned to one of several **tiers** based on their
required freshness:

- **Hot tier** — refreshes as fast as possible, ahead of all other tables
- **Warm tier** — refreshes at the normal configured interval
- **Cold tier** — refreshes only when hot and warm tiers are idle

You can assign a stream table to a tier explicitly, or let AUTO mode
determine the appropriate tier based on the configured `sla` (staleness
deadline). A stream table with an SLA of "never more than 10 seconds stale"
is automatically promoted to the hot tier during periods of high activity.

*In plain terms:* the customer-facing leaderboard gets refreshed before the
nightly background rollup — without any manual tuning.

---

## UNLOGGED Change Buffers

Change buffers are the temporary tables where pg_trickle stores captured
row changes before they are applied to stream tables during the next refresh.
These buffers are transient — they do not need to survive a database crash,
because the change capture triggers will replay the changes from the source
tables on restart.

By making change buffers **UNLOGGED** (a PostgreSQL table option that skips
write-ahead logging), write operations to the change buffer are significantly
faster. The tradeoff — that the buffer is empty after a crash — is acceptable
because the data can be recaptured.

*In plain terms:* capturing changes into the buffer is now faster, with no
correctness impact.

---

## Refresh Mode Diagnostics

A new diagnostic function `pgtrickle.explain_refresh_decision(name)` returns
a detailed explanation of why the last refresh used DIFFERENTIAL, FULL, or
AUTO, including the specific metrics that drove the decision:

- The delta size as a fraction of the total table size
- The measured cost of the last DIFFERENTIAL refresh
- The measured cost of the last FULL refresh
- The AUTO mode threshold and how far the delta was from the threshold

*In plain terms:* you can now understand exactly why pg_trickle chose to
do a full refresh instead of a differential one, and tune accordingly.

---

## Error-State Circuit Breaker Improvements

The circuit breaker from v0.11.0 received improvements: the error-state
information is now surfaced in `pg_stat_stream_tables` with the specific
error message, and the breaker can be reset manually with
`pgtrickle.reset_fuse(name)` without needing to drop and recreate the
stream table.

---

## TUI Dashboard

A **terminal user interface (TUI) dashboard** — accessible via the
`pgtrickle-tui` command-line tool — shows a live overview of all stream
tables: their current status, last refresh time, refresh latency, error
state, and tier assignment. It updates in real time.

*In plain terms:* run `pgtrickle-tui` in a terminal and see at a glance
what all your stream tables are doing, without writing any SQL.

---

## GHCR Docker Images

Official Docker images are now published to the **GitHub Container Registry
(ghcr.io)**, making it easier to run pg_trickle in container environments
without building from source.

---

## Scope

v0.14.0 introduces tiered scheduling (the biggest operational improvement
since the event-driven scheduler in v0.11.0), UNLOGGED buffers for
performance, and the TUI dashboard for observability. Together these represent
a significant step toward production-friendly operations.