docs(postgres): document the replication_acceleration_rebuilt metric

[claudespice]

Summary

spiceai/spiceai#13350 registers a new auto-registered Postgres replication metric, replication_acceleration_rebuilt, which the docs did not carry. It is the signal for a condition both Postgres pages already describe at length but gave no way to observe: an acceleration that was rebuilt from the source on its last attach instead of resuming from its recorded position — a full re-read of the table that nobody asked for.

Verified against origin/trunk:

• Registration: crates/data-connectors/connector-postgres/src/replication.rs:845-862 — MetricSpec::new("replication_acceleration_rebuilt", MetricType::ObservableGaugeU64).auto_register(). That is 27 specs in the array against the 26 rows the deployment guide listed.
• Observation: same file, lines 1079-1090 — it observes 1 only when rebuild_cause() is Some, with a cause attribute pushed onto the dataset attributes. A dataset that resumed reports no series rather than a constant 0, so both pages say to alert on presence, not value.
• cause values: crates/data_components/src/postgres_replication/mod.rs:366-374 — no_record, foreign_source, unreadable, rewound_source, acknowledged_past, retention_lost, copied verbatim. Their meanings are from the RebuildCause variant docs (same file, lines 332-359), including the two the code calls out explicitly: acknowledged_past is not a WAL retention problem, and rewound_source is reason to check whether other datasets on the same source resumed when they should not have.

Pages changed

• website/docs/components/data-connectors/postgres/deployment.md — the metric row, plus the cause attribute in the trailing attributes sentence.
• website/docs/features/cdc/postgres-replication.md — a new Detecting an unplanned rebuild section mapping each cause onto the rebuild/resume decision table already above it, a row in the core-signals table, and a pointer from the "whole table is re-read on a restart that used to resume" troubleshooting row.

Cross-page grep: grep -rln "replication_inserts_total" website/docs/ → these two Postgres pages and features/cdc/mysql-replication.md; the MySQL page carries a different connector's metric set and is unaffected.

Scope

vNext only (addition). spiceai/spiceai#13350 merged 2026-08-26 as c04c6cff08, after the v2.2.0 tag (2026-08-24); git tag --contains c04c6cff08 is empty, so no released snapshot has this metric.

Source PRs

• feat(postgres): outstanding write-back xid registry for CDC echo suppression spiceai#13350 — feat(postgres): outstanding write-back xid registry for CDC echo suppression

Test plan

• cd website && npm run build passes (new {#unplanned-rebuilds} anchor and the cross-page link to it resolve)
• Versioned-docs propagation checked — addition, vNext only
• Files updated: 2

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: claudespice

[github-actions]

🚀 deployed to https://00e4173a.spiceai-org-website.pages.dev

[claudespice]

@copilot review

[Copilot]

🟡 Changes recommended

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents the PostgreSQL acceleration rebuild metric and its diagnostic causes.

Changes:

• Adds the metric to PostgreSQL metric references.
• Explains rebuild causes and alerting behavior.
• Links troubleshooting guidance to the new section.

File summaries

File	Description
website/docs/features/cdc/postgres-replication.md	Documents rebuild detection, causes, and troubleshooting.
website/docs/components/data-connectors/postgres/deployment.md	Adds the metric and its attributes.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

@copilot review

Updated the troubleshooting wording to cover all rebuild causes in commit 7b61927 and re-ran automated checks.