Skip to content

docs: correct cancel_timer, autovacuum and fetch_unprocessed docstrings, document ping - #234

Merged
lesnik512 merged 1 commit into
mainfrom
docs/small-review-fixes
Oct 17, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/small-review-fixes

Conversation

@lesnik512

Copy link
Copy Markdown
Member

For 0.15.1, no issue: four docstrings and one docs paragraph that were wrong or left out something operators need. No code change.

  • cancel_timer: the docstring said a claimed row's delivery "completes normally". If the worker that claimed it died, the lease stays set until lease_ttl_seconds passes and the row is delivered again, and cancel_timer keeps returning False the whole time. The docstring now says so.
  • autovacuum.py: the module docstring said the default vacuum threshold grows with the bloated table size. It grows with the live row count (reltuples), so the real problem is a large backlog, which delays vacuum exactly when churn is highest. The recommendation itself doesn't change.
  • fetch_unprocessed: no index covers the queue filter, so a call for a rare or empty queue reads the whole table. The docstring now says to keep it for tests and occasional inspection.
  • broker.ping(): it had no docstring. Its database check takes a connection from the engine's pool, so it also fails, after up to 5 seconds, when the application's own sessions hold every pooled connection. The new docstring and the Prometheus/OpenTelemetry setup page, which called make_ping_asgi a liveness probe, now recommend it as a readiness probe, or leaving the pool room for it behind a liveness probe.

That last point is the review finding about ping() failing while the pool is busy. Since #230, the subscribers can't exhaust the pool on their own. The case left is the application's own sessions using every connection, and failing the probe there is arguably right. Making ping() skip the pool would need SQLAlchemy internals, so this PR documents the behaviour instead.

Verification

  • 704 tests pass in docker.
  • ruff and ty are clean, and the docs build.

@github-actions

Copy link
Copy Markdown

Benchmark gate

✅ gate passed

scenario msg/s delete/msg WALrec/msg WALB/msg fpi upd del dead_tup
consumer/w1/b10 1235 1.000 6.69 913 242 5000 5000 10000
consumer/w1/b100 1364 1.000 7.09 1143 243 5000 5000 10000
consumer/w2/b10 1552 1.000 6.69 914 242 5000 5000 10000
consumer/w2/b100 1758 1.000 7.09 1143 243 5000 5000 10000
consumer/w4/b10 1589 1.000 6.72 940 242 5000 5000 10000
consumer/w4/b100 1897 1.000 7.09 1142 243 5000 5000 10000
consumer/w1/b100/tfbs100 6018 0.010 6.07 1121 245 5000 5000 10000
consumer/w1/b100/interval1-10 1403 1.000 7.09 1143 243 5000 5000 10000
producer/w1/b100 2883 0.000 3.04 597 1 0 0 0
producer/w1/b100/ppt1 717 0.000 4.04 637 1 0 0 0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls and other_calls within +2; wal_records within a 10% band; fetch_calls within 2x. msg/s, WAL bytes and total calls are informational (timing/FPI noise).

@lesnik512
lesnik512 merged commit 88e505b into main Oct 17, 2026
13 checks passed
@lesnik512
lesnik512 deleted the docs/small-review-fixes branch October 17, 2026 13:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant