Plain-language companion: v0.2.1.md

v0.2.1 — Upgrade Infrastructure & Documentation

Status: Released (2026-03-05).

Patch release focused on upgrade safety, documentation, and three catalog schema additions via sql/pg_trickle--0.2.0--0.2.1.sql:

  • has_keyless_source BOOLEAN NOT NULL DEFAULT FALSE — EC-06 keyless source flag; changes apply strategy from MERGE to counted DELETE when set.
  • function_hashes TEXT — EC-16 function-body hash map; forces a full refresh when a referenced function’s body changes silently.
  • topk_offset INT — OS2 catalog field for paged TopK OFFSET support, shipped and used in this release.

Upgrade Migration Infrastructure ✅

In plain terms: When you run ALTER EXTENSION pg_trickle UPDATE, all your stream tables should survive intact. This adds the safety net that makes that true: automated scripts that check every upgrade script covers all database objects, real end-to-end tests that actually perform the upgrade in a test container, and CI gates that catch regressions before they reach users.

Complete safety net for ALTER EXTENSION pg_trickle UPDATE:

Item Description Status
U1 scripts/check_upgrade_completeness.sh — CI completeness checker ✅ Done
U2 sql/archive/ with archived SQL baselines per version ✅ Done
U3 tests/Dockerfile.e2e-upgrade for real upgrade tests ✅ Done
U4 6 upgrade E2E tests (function parity, stream table survival, etc.) ✅ Done
U5 CI: upgrade-check (every PR) + upgrade-e2e (push-to-main) ✅ Done
U6 docs/UPGRADING.md user-facing upgrade guide ✅ Done
U7 just check-upgrade, just build-upgrade-image, just test-upgrade ✅ Done
U8 Fixed 0.1.3→0.2.0 upgrade script (was no-op placeholder) ✅ Done

Documentation Expansion ✅

In plain terms: Added six new pages to the documentation book: a dbt integration guide, contributing guide, security policy, release process, a comparison with the pg_ivm extension, and a deep-dive explaining why row-level triggers were chosen over logical replication for CDC.

GitHub Pages book grew from 14 to 20 pages:

Page Section Source
dbt Integration Integrations dbt-pgtrickle/README.md
Contributing Reference CONTRIBUTING.md
Security Policy Reference SECURITY.md
Release Process Reference docs/RELEASE.md
pg_ivm Comparison Research plans/ecosystem/GAP_PG_IVM_COMPARISON.md
Triggers vs Replication Research plans/sql/REPORT_TRIGGERS_VS_REPLICATION.md

Exit criteria: - [x] ALTER EXTENSION pg_trickle UPDATE from 0.1.3→0.2.0 tested end-to-end - [x] Completeness check passes (upgrade script covers all pgrx-generated SQL objects) - [x] CI enforces upgrade script completeness on every PR - [x] All documentation pages build and render in mdBook