# Operation Matrix

For full step-by-step procedures and runnable command templates, read [operation-guide.md](operation-guide.md) first. Use this file as a compact lookup table.

## Core actions

| Action | CLI | API | Precondition | Notes |
| --- | --- | --- | --- | --- |
| Create | `cdc cli changefeed create` | `POST /api/v2/changefeeds` | `sink_uri` required | CLI starts from default config and then applies `--config`; API create can also include `replica_config`, and `changefeed_id` may be omitted to auto-generate one. |
| List | `cdc cli changefeed list` | `GET /api/v2/changefeeds` | None | CLI only controls `removed/finished` visibility via `--all`; API supports `state=all|normal|pending|warning|stopped|failed|removed|finished`, and the response shape is `{total, items}`. |
| Query | `cdc cli changefeed query` | `GET /api/v2/changefeeds/{id}` | Changefeed exists | CLI `-s/--simple` returns a simplified status view; API returns full details. |
| Pause | `cdc cli changefeed pause` | `POST /api/v2/changefeeds/{id}/pause` | Changefeed exists | After a successful call, still poll until the state becomes `stopped`. |
| Resume | `cdc cli changefeed resume` | `POST /api/v2/changefeeds/{id}/resume` | Changefeed is `stopped` or needs resume flow | CLI supports `--overwrite-checkpoint-ts=now`; API only accepts numeric `overwrite_checkpoint_ts`. |
| Remove | `cdc cli changefeed remove` | `DELETE /api/v2/changefeeds/{id}` | None | API delete is idempotent; CLI re-queries to confirm actual deletion. |
| Update | `cdc cli changefeed update` | `PUT /api/v2/changefeeds/{id}` | Changefeed must be `stopped` or `failed` | Prefer the fixed lifecycle `pause -> update -> resume`. |

## Parameter mapping

| Concern | CLI | API | Notes |
| --- | --- | --- | --- |
| Server address | `--server=http://host:8300` | Base URL `http://host:8300/api/v2/...` | Both point directly to the TiCDC HTTP service. |
| Keyspace | `--keyspace` / `-k` | `?keyspace=` query parameter | Always pass it explicitly to avoid CLI default mismatches. In OpenAPI v2, the query parameter is authoritative and overrides any `keyspace` value in the JSON body. |
| Changefeed ID | `--changefeed-id` / `-c` | URL path or body field `changefeed_id` | The ID must match `^[a-zA-Z0-9]+(\\-[a-zA-Z0-9]+)*$`. |
| Sink URI | `--sink-uri` | JSON `sink_uri` | Special characters must be URL-encoded. |
| Config file | `--config=/path/changefeed.toml` | Convert TOML to JSON `replica_config` | CLI update merges TOML into the current config; API update must not treat partial TOML as a full `replica_config`. |
| Target TSO | `--target-ts` | JSON `target_ts` | `target_ts` must be greater than `start_ts`. |
| Resume checkpoint | `--overwrite-checkpoint-ts` | JSON `overwrite_checkpoint_ts` | Moving checkpoint forward can lose data; moving it backward can create duplicates. |

## Update-specific differences

- CLI create:
  - Creation starts from default config and then applies the TOML file.
- CLI update:
  - Update reads the current changefeed config first and then applies the TOML patch onto it.
- CLI create/update with `--no-confirm`:
  - It skips prompts, and if verification finds ineligible tables it also forces `ignore_ineligible_table=true`.
- API update:
  - If the request body contains `replica_config`, the server replaces the current config with the provided `replica_config` and only then validates it.
  - Omitted `replica_config` fields fall back to defaults rather than preserving the old config.
  - Therefore, API update should treat `replica_config` as a full object, not as a partial patch.

## Suggested verification

- Create or resume:
  - Query until `state == normal`.
- Pause:
  - Query until `state == stopped`.
- Update:
  - Query current config again and compare `sink_uri`, `target_ts`, and `config`.
- Remove:
  - Re-query and expect not found or the expected terminal state.

## Optional validation targets

- Product docs:
  - the current docs in `https://github.com/pingcap/docs` on `master`
  - the matching `release-x.y` branch in the same repo when version-specific behavior must be checked
  - under `ticdc/`, especially the changefeed management, OpenAPI v2, and changefeed config docs
- CLI source, if a TiCDC checkout is available:
  - the changefeed create, update, pause, resume, remove, query, and list handlers
- API source, if a TiCDC checkout is available:
  - the OpenAPI v2 changefeed handlers and request model definitions