Why would you set heartbeat.interval.ms on a Debezium Postgres connector capturing a low-traffic table?

## The failure this prevents A PostgreSQL replication slot guarantees that the server keeps every write-ahead log record the consumer has not yet confirmed. That guarantee is the whole point of a slot — it is why a Debezium connector can be stopped for an hour and resume without losing changes — and it is also a loaded gun. Retention is bounded by consumer progress, not by time or size, unless an administrator has explicitly capped it. A slot whose confirmed position stops moving pins WAL indefinitely, and the symptom is a database disk filling steadily until Postgres refuses writes. The database looks healthy right up to the moment it isn't. The surprising part is that a *running, healthy* connector can cause this. ## Why an idle connector stops confirming Debezium advances its recorded position as a side effect of producing change events. Produce nothing and there is nothing to flush, so the last confirmed position stays put. Two shapes of workload trigger it: **A quiet captured table.** You capture `public.exchange_rates`, updated twice a day. Between updates the connector idles. Meanwhile every other table in the same database is busy, WAL keeps being written, and the slot's confirmed position lags further behind the log's head with every transaction. **Writes in a different database of the same cluster.** This one is worse and less obvious. Logical decoding in Postgres is scoped to a single database, so a connector attached to `analytics` is not shown changes made in `orders` at all. It cannot advance past them by decoding them, because it never sees them. From the connector's point of view the source is completely still; from the server's point of view the WAL is growing fast. ## What heartbeats do `heartbeat.interval.ms` defaults to `0`, meaning disabled. Set it to something on the order of seconds-to-tens-of-seconds and the connector emits a heartbeat record to `__debezium-heartbeat.<topic.prefix>` on that schedule. That record is a real produced event, so it carries the connector's current source position and gives it a reason to flush an offset. The slot advances, and Postgres can recycle WAL up to the confirmed point. Heartbeats have two secondary benefits worth naming. They keep the network connection and any intermediate proxies from timing out an idle replication connection, and they give monitoring a positive liveness signal: a topic that has gone quiet distinguishes 'the connector is fine, the source is quiet' from 'the connector is wedged'. Without them those two states look identical from the outside. ## When heartbeats alone are not enough In the cross-database case, emitting heartbeats lets the connector re-flush the position it already has — but that position cannot move past changes it is never given. The fix is `heartbeat.action.query`: a statement Debezium executes against the *captured* database on each heartbeat tick. The idiomatic version inserts or updates a row in a tiny dedicated table: ```sql CREATE TABLE dbz_heartbeat (id int PRIMARY KEY, ts timestamptz); ``` with the action query updating it. That write produces WAL *in the captured database*, which logical decoding does deliver to the connector, which then confirms a fresh position and unblocks retention. Keep the heartbeat table out of your include list, or accept a steady trickle of uninteresting change events on a topic. ## Other engines The setting is not Postgres-only. On SQL Server and Oracle, heartbeats keep an otherwise idle connection alive and keep the recorded position fresh so a restart does not re-read a long stretch of log. Postgres is where the consequence of skipping it is catastrophic rather than merely inconvenient, because of the slot's unbounded retention. ## Operating it Heartbeats are a mitigation, not a monitor. Independently alert on slot lag — the distance between the current log position and each slot's confirmed position — and on the age of the oldest unconfirmed position. Alert on the *derivative* too: a slot that has not moved in ten minutes on a busy cluster is a problem long before the disk is full. Consider bounding retention at the server level so that a runaway slot is invalidated rather than allowed to take the database down, and make sure that trade-off is a deliberate decision: an invalidated slot means the connector loses its place and needs a fresh backfill, which is often still preferable to an outage. Also watch the operational trap of a *stopped* connector. Heartbeats do nothing for a connector that is not running, and a slot left behind by a decommissioned connector is the classic cause of a disk-full incident weeks later. Deleting the connector must include dropping its slot.