Plain-language companion: v0.32.0.md

v0.32.0 — Citus: Stable Naming & Per-Source Frontier Foundation

Status: Planned. Derived from plans/ecosystem/PLAN_CITUS.md §6 Phase 1 and Phase 2.

Release Theme v0.32.0 is the first of two releases delivering world-class Citus support. It ships two additive, non-breaking layers: (1) a src/citus.rs module with Citus detection and placement helpers; and (2) a stable-hash naming scheme that replaces OID-keyed internal objects (changes_{oid}, pg_trickle_cdc_fn_{oid}, slot names, frontier keys) with names derived from stable_hash(database_oid || '/' || schema || '.' || table). Both layers produce immediate quality benefits for all users — stable names survive pg_dump/restore and major-version upgrades — and they are mandatory prerequisites for v0.35.0’s per-worker slot CDC. There is zero behaviour change on a single-node deployment.

Correctness

ID Title Effort Priority
CITUS-1 src/citus.rs: detection helpers and placement query M P0
CITUS-2 SourceIdentifier struct carrying (oid, stable_name) S P0
CITUS-3 Catalog migration: add source_stable_name, source_placement, st_placement columns S P0
CITUS-4 Rename all OID-keyed objects to stable_name form M P0
CITUS-5 Frontier rekey: Frontier.sources from OID string to stable_name S P1
CITUS-6 Audit and remove cross-source global LSN comparisons M P1
CITUS-7 Add frontier_per_node JSONB column for distributed sources S P1
CITUS-8 SQL migration: rename existing changes_{oid} tables and trigger functions in a single transaction M P0

CITUS-1 — New module src/citus.rs. Detection helpers: - is_citus_loaded() — SELECT 1 FROM pg_extension WHERE extname='citus' - placement(oid) → Local | Reference | Distributed { dist_column } via pg_dist_partition - worker_nodes() → Vec<NodeAddr> from pg_dist_node - shard_placements(table_oid) — which workers host shards

None of these panic if Citus is absent; all return sensible defaults (Local, empty vecs). Citus-specific code paths are always guarded by is_citus_loaded().

CITUS-2 — SourceIdentifier { oid: pg_sys::Oid, stable_name: String }. stable_name = lower_hex(FNV-1a-64(database_oid || "/" || schema || "." || table))[..16]. Deterministic, short, URL-safe, identical on every Citus node. Serialised in pgt_change_tracking.source_stable_name and used for all object names.

CITUS-3 — Schema changes (nullable, backward-compatible): sql ALTER TABLE pgtrickle.pgt_change_tracking ADD COLUMN source_stable_name TEXT, ADD COLUMN source_placement TEXT NOT NULL DEFAULT 'local'; ALTER TABLE pgtrickle.pgt_dependencies ADD COLUMN source_stable_name TEXT, ADD COLUMN source_placement TEXT NOT NULL DEFAULT 'local'; ALTER TABLE pgtrickle.pgt_stream_tables ADD COLUMN st_placement TEXT NOT NULL DEFAULT 'local'; Old rows receive a synthetic stable name (hash of existing OID-based name) and continue to function unchanged.

CITUS-4 — Replace changes_{oid}, pg_trickle_cdc_ins_{oid}, pg_trickle_cdc_fn_{oid}, idx_changes_{oid}_*, WAL slot names (pgtrickle_{oid}), and the __PGS_PREV_LSN_{oid}__ placeholder tokens in src/dvm/diff.rs with {stable_name} forms. Affected files: src/cdc.rs, src/wal_decoder.rs, src/dvm/diff.rs, src/refresh/codegen.rs, src/dvm/operators/*.

CITUS-5 / CITUS-6 — Frontier.sources is already a HashMap; rekey from OID string to stable_name. Audit src/refresh/codegen.rs and src/scheduler.rs for reads of pg_current_wal_lsn() used in cross-source comparisons; replace with per-source watermark logic from src/wal_decoder.rs.

CITUS-7 — Add frontier_per_node JSONB to pgt_change_tracking for distributed sources. When the source is Local this column is NULL; for Distributed sources it records { "worker_id": lsn, ... } tuples.

CITUS-8 — sql/pg_trickle--<prev>--<next>.sql performs column adds then backfills source_stable_name from pg_class + pg_namespace, renames existing buffer tables and trigger functions to the stable-hash form, updates the WAL slot name in pg_replication_slots (via pg_rename_logical_replication_slot where available), and updates pgt_change_tracking. Provides a downgrade path in the same file.

Stability

ID Title Effort Priority
STAB-1 Keep OID-based lookup as fallback for rows without source_stable_name S P0
STAB-2 Detect and surface a clear error if stable hash collides (astronomically unlikely; check at create time) S P1

Test Coverage

ID Title Effort Priority
TEST-1 Unit tests for stable_hash() — known vectors, cross-platform determinism S P0
TEST-2 Unit tests for SourceIdentifier round-trip serialisation S P0
TEST-3 Integration: pg_dump / pg_restore cycle preserves stream table with stable-named objects M P0
TEST-4 Integration: major-version upgrade simulation — OID changes, stable name unchanged M P1
TEST-5 Integration: frontier rekey — multi-source ST with different write rates converges correctly M P0
TEST-6 Integration: existing installation upgrade (v0.31.0 → v0.32.0) renames objects correctly M P0

Documentation

ID Title Effort Priority
DOCS-1 Changelog entry explaining stable naming motivation S P0
DOCS-2 Upgrade guide: what changes, what to expect, rollback instructions S P0

Exit Criteria

  • [ ] CITUS-1: is_citus_loaded(), placement(), worker_nodes() compile and return sensible defaults when Citus is absent
  • [ ] CITUS-2: stable_hash("public.orders") produces identical output on two fresh PG instances with different OIDs
  • [ ] CITUS-4: no {oid} tokens remain in object names created by setup_cdc_for_source()
  • [ ] CITUS-8: migration script renames all existing objects; just test-upgrade-all passes
  • [ ] TEST-3: pg_dump / pg_restore round-trip test passes
  • [ ] TEST-6: v0.31.0 → v0.32.0 upgrade integration test passes
  • [ ] Zero performance regression on the single-node benchmark suite (Citus detection check adds ≤ 1 µs per create_stream_table() call when Citus is absent)
  • [ ] just check-version-sync passes
  • [ ] just lint passes (zero warnings)