Documentation Index
Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt
Use this file to discover all available pages before exploring further.
Backpressure prevents unbounded growth of staged rows in the cloud and gives devices a signal to stop sending when the server cannot keep up.
Two pause mechanisms
| Mechanism | Trigger | Device downlink? | Device keeps publishing? |
|---|
| Schema review pause | Ambiguous/breaking schema | No | Yes — server stages |
| Volume backpressure | Staged rows exceed cap | pause_lineage | No — buffer locally |
| Materialization circuit breaker | Repeated mirror write failures | pause_lineage | No — buffer locally |
paused in Postgres, but only volume/CB paths send MQTT downlink controls.
Volume thresholds (defaults)
Per lineage, configured in edge replication policy:
| Setting | Default |
|---|
max_pending_rows_per_lineage | 100,000 rows |
max_pending_bytes_per_lineage | 1 GiB |
resume_threshold_percent | 80% |
- Insert
edge_pending_controls row (pause_lineage).
- Set lineage
paused.
- Publish
integration.edge_ingest_control.requested.v1 → broker delivers sync/ingest/control.
- Device ACKs, stops publishing that source_table, buffers durably.
When both metrics fall below 80% of caps, sweepBackpressureResume:
- Sets lineage
active.
- Sends
resume_lineage downlink with server_watermark.
Device protocol
On pause_lineage
1. ACK immediately on sync/ingest/ack
2. Stop publishing batches for source_table
3. Buffer new journal rows locally (state.db + durable queue)
4. Record server_watermark from control message
On resume_lineage
1. ACK immediately
2. Drain buffer in commit_seq order starting at server_watermark + 1
3. Resume normal 5s flush loop
Lineage-scoped pause
Pause affects one SQLite table on one device. Other tables on the same device continue syncing.
Example: device_state paused for backpressure; order_events still publishes.
Materialization circuit breaker
Separate from volume caps:
- After 5 permanent materialization errors, lineage pauses and device receives
pause_lineage.
- Operator inspects materialization error on lineage detail.
- Fix binding/DDL/TSDB issue.
- Call
POST .../lineages/{id}/reset-materialization to clear counter and optionally trigger resume_lineage.
platform-tui: lineage detail → x when materialization error section is present.
TUI x reset applies to materialization circuit breaker, not volume backpressure. For volume pause, wait for auto-resume sweep or reduce staged backlog operationally.
Monitoring
| Signal | Where |
|---|
Lineage paused + no open review | Likely backpressure or CB |
edge_pending_controls open rows | Pending downlink / unacked control |
| Staged row count growing | Approaching cap — approve schema or scale worker/TSDB |
| Device logs “pause_lineage” | Device correctly buffering |
platform-tui events watch
# Look for integration.edge_table_lineage.ingestion_paused
Operator responses
| Situation | Action |
|---|
| Pause during schema review | Normal — approve schema |
| Pause + staged at cap + no review | Wait for auto-resume or investigate worker health |
| Device offline during pause | QoS 1 downlink buffered by broker (persistent session) |
| Buffer lost on device after long pause | Plan bootstrap snapshot (secondary flow) when available |
