[#31220] CDC: Add cleanup_stale_cdc_streams yb-admin command

[egladysh]

Summary

Adds a CleanupStaleCDCStreams RPC to the MasterReplication master service and a corresponding cleanup_stale_cdc_streams yb-admin command.

The command scans the cdc_state table and identifies stale entries — rows whose CDC stream no longer exists, or whose tablet no longer exists. It supports:

• An optional YSQL database name to restrict cleanup to entries attributable to a single namespace. Entries whose stream and tablet metadata are both missing cannot be attributed to any namespace and are only removed in an unfiltered (all-namespaces) invocation.
• A --dry_run flag to report stale entries without deleting them.

Example (dry run):

./bin/yb-admin \
    --master_addresses 127.0.0.1:7100 \
    --dry_run \
    cleanup_stale_cdc_streams yugabyte

Filtering stale CDC state entries for YSQL database: yugabyte

Found 2 stale cdc_state entries (dry run).
  tablet_id: 8f3b9b3a8b2c4e2b9c7d6a5f4e3d2c1b, stream_id: 3d9f1e2a4b6c4d8e9f0123456789abcd, table_id: 000033e8000030008000000000004000, table_name: orders, reason: stream not found
  tablet_id: missing_tablet_id, stream_id: 7a8b9c0d1e2f34567890abcdef123456, reason: tablet not found

Documentation for the new command is added under the yb-admin Change Data Capture commands in docs/content/stable/admin/yb-admin.md.

Implementation notes:

• The cdc_state table is scanned once and materialized so both the tablet-collection and classification loops share one consistent snapshot.
• Tablet table metadata is resolved under a single SharedLock before the classification loop to avoid repeated lock acquisitions.
• xCluster streams that carry an empty namespace_id have their namespace resolved via their first table_id.

Upgrade/Rollback safety

The proto change is purely additive: new messages (CleanupStaleCDCStreamsRequestPB, CleanupStaleCDCStreamsResponsePB) and a new RPC method (CleanupStaleCDCStreams) are added to MasterReplication. No existing message fields are modified.

On a mixed-version cluster, an older master that does not have this RPC will return UNIMPLEMENTED when cleanup_stale_cdc_streams is invoked; all other CDC and xCluster operations are unaffected.

Rolling back removes the yb-admin command and the RPC handler. No on-disk state, catalog schema, or gflag defaults are changed.

Test plan

• CDCServiceTest.TestCleanupStaleCDCStreamsWithoutCDCStateTable — verifies OBJECT_NOT_FOUND when the cdc_state table does not exist.
• CDCServiceTest.TestCleanupStaleCDCStreamsDryRunAndDelete — dry-run returns stale entries without deleting; live run deletes exactly those entries and leaves the valid entry untouched.
• CDCServiceTest.TestCleanupStaleCDCStreamsNamespaceFilter — with a namespace filter, only entries attributable to the selected namespace are deleted; cross-namespace and unattributable (both stream and tablet missing) entries are preserved.

[netlify]

✅ Deploy Preview for infallible-bardeen-164bc9 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	fc64afe
🔍 Latest deploy log	https://app.netlify.com/projects/infallible-bardeen-164bc9/deploys/6a20b71863992f000845e990
😎 Deploy Preview	https://deploy-preview-32025--infallible-bardeen-164bc9.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gemini-code-assist]

Code Review

This pull request introduces a new administrative command cleanup_stale_cdc_streams to yb-admin (along with the corresponding master RPC CleanupStaleCDCStreams) to identify and purge stale entries from the cdc_state table when their associated streams or tablets no longer exist. The changes include documentation, integration tests, and CLI/client support. The review feedback highlights a potential null pointer dereference of cdc_state_table_ in CatalogManager::CleanupStaleCDCStreams before calling GetTableRangeAsync, which could cause a master crash if the table is uninitialized; adding a defensive null check is recommended.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[asrinivasanyb]

Could we follow a test pattern similar to CDCSDKYsqlTest::TestValidationAndSyncOfCDCStateEntriesAfterUserTableRemoval - this tests the yb-admin command directly

[egladysh]

I'll take a look.

[egladysh]

@asrinivasanyb To confirm, you're after the yb-admin CLI-as-subprocess pattern, not relocating this into the CDCSDKYsqlTest fixture, right?

[asrinivasanyb]

Why do we need 2 passes over the cdc_state table ?

[egladysh]

This is only one pass over cdc_state? We materialize CDCStateTableRange. The later loops are over the in-memory all_entry_keys vector: first to collect candidate tablet IDs for batched metadata lookup, and then to classify rows using that metadata.

[asrinivasanyb]

isn't this required only for the colocated table case ?

[egladysh]

It is used for both colocated and non-colocated tablets. For non-colocated tablets this normally contains the single user table for the tablet. For colocated tablets it can contain multiple tables, so the same map lets us report all resolved table metadata.