RDSC-4929: Clarify SQL Server schema migration and capture history limits

[ZdravkoDonev-redis]

SQL Server's existing capture instance can continue emitting the old column structure after a schema change, so an added column can be omitted without an error. The preparation guide currently describes this as always producing errors, and the FAQ implies automatic column handling also applies to SQL Server.

This change explains the SQL Server exception, links the FAQ to the migration procedure, and gives RDI-specific offline migration steps when the online transition gap is unacceptable. The procedure pauses application writes, checks that final changes reached the target, stops and starts only the SQL Server source with the RDI CLI, and verifies the updated columns before deleting old capture history. It also adds the missing consequence of deleting the old capture instance: changes available only in its change table cannot be recovered by rewinding an offset. Retention cleanup and the two capture instance limit still apply while the old instance is retained. The final check verifies column values rather than only continued streaming or row counts.

Validation:

• git diff --check passes.
• Focused RDI Hugo build passes with CI's Hugo 0.143.1. The rendered SQL Server paragraphs, FAQ link and target anchor, and external links were checked.
• A full site build was not completed. The focused build warns about non-RDI pages excluded from its content mount. The host's newer Hugo 0.154.2 also encounters an existing docs navigation template incompatibility; the CI version passes.

Sources: Debezium SQL Server schema evolution, Microsoft capture-instance deletion, and Microsoft CDC retention and instance limits.

Related offset research: RDI PR #2885.

---

Note

Low Risk
Documentation-only updates to SQL Server CDC schema migration guidance; no runtime or product code changes.

Overview
Corrects SQL Server CDC schema-change behavior in the RDI prep guide and FAQ: schema updates no longer described as always causing errors; the docs now state that the existing capture instance keeps the old column layout, so new columns can be omitted silently until a new capture instance is created.

The online migration steps are tightened (transition-window caveats, when to use offline migration, post-migration column-value verification). Dropping the old capture instance now documents non-recoverable history, CDC retention, and the two capture-instance-per-table limit.

Adds a new “Update the schema offline” section with RDI-specific steps (redis-di describe / stop / start, suspend writes, deploy config if columns/transformations changed). The FAQ now calls out SQL Server as an exception to automatic column tracking and links to the migration guide.

^{Reviewed by Cursor Bugbot for commit 7f3440e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Staging links:
https://redis.io/docs/staging/rdsc-4929-rdi-sqlserver-schema-replay/integrate/redis-data-integration/data-pipelines/prepare-dbs/sql-server/
https://redis.io/docs/staging/rdsc-4929-rdi-sqlserver-schema-replay/integrate/redis-data-integration/faq/

[github-actions]

🧠 Redis Memory

Found 6 related items from repository history:

• PR — Clarify RDI snapshot modes and missed deletes

  When a saved source log position expires, when_needed can take a new snapshot and resume collection while leaving deleted rows in Redis. T

• PR — DOC-6573 RDI source prep updates for SQL Server on Azure

  References info in this ticket and the [Microsoft Azure CDC guide](https://learn.microso

• PR — DOC-6878 Expand RDI FAQ CDC section with all supported databases

  What

• PR — DOC-7142 Update RDI when-to-use limits for the Flink default; reunify Cloud and on-prem lists

  DOC-7142

• PR — DOC-6652 document CDC latency workaround for SQL Server on Azure

• Commit — RDSC-4929: Clarify SQL Server schema migration and capture history limits

  RDSC-4929: Clarify SQL Server schema migration and capture history limits

Memory updated at 7f3440e

[andy-stark-redis]

LGTM