---
name: manage-ticdc-changefeeds
description: Manage and identify TiCDC changefeeds through `cdc cli`, OpenAPI v2, or TiDB Cloud Ops metadata. Use this skill to map an Ops Portal changefeed display name to its numeric TiCDC ID, create, list, query, pause, resume, remove, or update changefeeds, change `sink_uri`, translate between CLI flags, TOML config, and JSON payloads, and verify safe update workflows against the TiCDC repository or a live cluster.
---

# Manage TiCDC Changefeeds

This is a host-agnostic skill for TiCDC changefeed operations.

If the hosting system ships product-specific files under `agents/`, treat them as optional UI metadata only.

## When To Use This Skill

Use this skill when the task involves any of the following:

- create, list, query, pause, resume, remove, or update a TiCDC changefeed
- change a changefeed `sink_uri`, `target_ts`, or replica config
- translate between `cdc cli` flags, changefeed TOML, and OpenAPI v2 JSON payloads
- explain or verify the safe lifecycle for a changefeed update

## Start Here

Read the bundled references in this order:

1. [references/operation-guide.md](references/operation-guide.md)
2. [references/operation-matrix.md](references/operation-matrix.md)
3. [references/update-playbook.md](references/update-playbook.md)

Use them this way:

- `operation-guide.md`: the primary, self-contained operating document
- `operation-matrix.md`: compact command, endpoint, and parameter lookup
- `update-playbook.md`: focused guidance for update, `sink_uri`, and checkpoint overwrite tasks

## TiDB Cloud Display Name Mapping

When the request refers to the product-facing name shown in Ops Portal, or asks for a
`changefeed name -> ID` mapping, read
[`../../platform/devops-api/tidb-tools-cdc/SUBSKILL.md`](../../platform/devops-api/tidb-tools-cdc/SUBSKILL.md).

Use that DevOps metadata endpoint before querying TiCDC metrics or OpenAPI. TiCDC
OpenAPI returns the runtime changefeed ID but does not own the Ops Portal
`display_name`. The mapping helper preserves `changefeed_id` for the
business/display ID and `internal_id` for the kernel/runtime TiCDC ID. Convert
`internal_id` to the common metrics label as `changefeed-<internal_id>` when
correlating with legacy TiCDC metrics.

## Minimal Operating Rules

- Always pass `keyspace` explicitly.
- Query the current changefeed before any state-changing or config-changing operation.
- Re-query after every write operation.
- For `sink_uri`, `target_ts`, or config changes, use `pause -> update -> resume`.
- Treat API `replica_config` as a full replacement, not a partial patch.
- If resume overwrites checkpoint ts, state the data-loss or duplicate-delivery risk before execution.

## Version Recheck Rules

- If the user does not specify a version, answer from the bundled guide first.
- If the user specifies a version, the bundled guide does not match the target environment, or runtime behavior disagrees with the default guide, re-check against `https://github.com/pingcap/docs`.
- In that repo, use `master` for the current docs view and `release-x.y` for version-specific validation.
- The TiCDC docs are usually under the `ticdc/` directory.
- If a local TiCDC source tree is available, use it only as optional validation for the target version.

## Response Expectations

When answering with this skill, include:

- whether the answer comes from the bundled guide only or was re-checked against a version-specific docs branch
- the exact CLI command, API request, or ordered procedure
- any assumption made because an input was missing
- the immediate verification step after the write operation