### Install TiCDC using TiUP

Source: https://github.com/pingcap/ticdc/blob/master/README.md

Installs the latest platform-specific TiCDC binary using the tiup command. Use --force to overwrite existing installations.

```bash
tiup install cdc --force
```

--------------------------------

### Start Debezium Services with Docker Compose

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/debezium01/README.md

Navigate to the Debezium integration test directory and start the necessary services using Docker Compose.

```bash
cd ticdc/tests/integration_tests/debezium
docker compose up
```

--------------------------------

### Start TiDB Playground

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/debezium01/README.md

Launch a local TiDB playground environment with specified configurations using tiup.

```bash
tiup playground nightly --tiflash 0 --ticdc 1 
```

--------------------------------

### Install GoLang for TiCDC Compilation (Linux)

Source: https://github.com/pingcap/ticdc/blob/master/README.md

Installs GoLang 1.25.8 on Linux systems. Ensure you have wget and sudo privileges.

```bash
# Linux
wget https://go.dev/dl/go1.25.8.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.8.linux-amd64.tar.gz
```

--------------------------------

### Install GoLang for TiCDC Compilation (MacOS)

Source: https://github.com/pingcap/ticdc/blob/master/README.md

Installs GoLang 1.25.8 on MacOS systems. Ensure you have curl and sudo privileges.

```bash
# MacOS
curl -O https://go.dev/dl/go1.25.8.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.8.darwin-amd64.tar.gz
```

--------------------------------

### Get All Tables for a Config

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieve all tables (eligible, ineligible, and all) matching replica config and filter rules, without performing sink verification. Requires start timestamp and replica configuration.

```bash
curl -X POST http://127.0.0.1:8300/api/v2/get_all_tables \
  -H "Content-Type: application/json" \
  -d '{
    "start_ts": 443100000000,
    "replica_config": {
      "filter": { "rules": ["mydb.*", "!mydb.tmp_*"] }
    }
  }'
```

--------------------------------

### Start TiCDC Server Node with New Architecture

Source: https://context7.com/pingcap/ticdc/llms.txt

Command to start a TiCDC server node. It requires specifying the PD cluster address, log file path, log level, and network addresses. The configuration file can enable the new architecture mode.

```bash
./cdc server \
  --pd="http://pd-host:2379" \
  --log-file="/var/log/ticdc/ticdc.log" \
  --log-level="info" \
  --addr="0.0.0.0:8300" \
  --advertise-addr="10.0.0.1:8300" \
  --config="/etc/ticdc/config.toml"
```

```toml
# [server]
# newarch = true
#
# [security]
# ca-path = "/etc/ssl/ca.crt"
# cert-path = "/etc/ssl/ticdc.crt"
# key-path = "/etc/ssl/ticdc.key"
```

--------------------------------

### Start a TiCDC server node

Source: https://context7.com/pingcap/ticdc/llms.txt

Starts a TiCDC node, connecting it to a PD cluster and enabling it to join or form a TiCDC cluster. Supports enabling the new architecture via configuration.

```APIDOC
## cdc server

### Description
Starts a TiCDC server node. This command connects to a PD cluster and joins or forms a TiCDC cluster. The new architecture can be enabled via the configuration file.

### Usage
```bash
./cdc server [flags]
```

### Flags
- **--pd** (string) - Required - The address of the PD cluster (e.g., "http://pd-host:2379").
- **--log-file** (string) - Optional - Path to the log file (e.g., "/var/log/ticdc/ticdc.log").
- **--log-level** (string) - Optional - Logging level (e.g., "info", "debug").
- **--addr** (string) - Optional - The listening address for the TiCDC node (e.g., "0.0.0.0:8300").
- **--advertise-addr** (string) - Optional - The advertised address for the TiCDC node (e.g., "10.0.0.1:8300").
- **--config** (string) - Optional - Path to the configuration file (e.g., "/etc/ticdc/config.toml").

### Configuration File Example (`config.toml`)
```toml
[server]
newarch = true

[security]
ca-path = "/etc/ssl/ca.crt"
cert-path = "/etc/ssl/ticdc.crt"
key-path = "/etc/ssl/ticdc.key"
```
```

--------------------------------

### DDL Configuration (Random Mode)

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/readme.md

Example TOML configuration for DDL workload in 'random' mode. The 'tables' field can be omitted.

```toml
mode = "random"

[rate_per_minute]
add_column = 10
drop_column = 10
add_index = 5
drop_index = 5
truncate_table = 0
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

This command runs all unit tests in the project. It's a good starting point for validating changes in shared utilities.

```bash
make unit_test
```

--------------------------------

### Create Changefeed with Full Replica Configuration

Source: https://context7.com/pingcap/ticdc/llms.txt

Example of creating a changefeed with a comprehensive replica configuration, including memory quota, filtering rules, sink settings, and scheduler options. All fields within replica_config are optional pointers.

```json
{
    "changefeed_id": "cf-full-config",
    "sink_uri": "kafka://broker:9092/topic?protocol=canal-json",
    "replica_config": {
      "memory_quota": 1073741824,
      "case_sensitive": false,
      "force_replicate": false,
      "ignore_ineligible_table": true,
      "enable_sync_point": false,
      "filter": {
        "rules": ["db1.*", "db2.orders", "!db2.tmp_*"],
        "ignore_txn_start_ts": [],
        "event_filters": [
          {
            "matcher": ["db1.audit_log"],
            "ignore_event": ["delete"],
            "ignore_sql": ["^DROP"]
          }
        ]
      },
      "sink": {
        "protocol": "canal-json",
        "dispatchers": [
          {
            "matcher": ["db1.*"],
            "partition": "ts",
            "topic": "db1-changes"
          }
        ],
        "kafka_config": {
          "partition_num": 6,
          "replication_factor": 3,
          "compression": "lz4",
          "required_acks": -1
        }
      },
      "scheduler": {
        "enable_table_across_nodes": true,
        "region_threshold": 10000
      },
      "changefeed_error_stuck_duration": 1800000000000
    }
  }
```

--------------------------------

### DDL Configuration (Fixed Mode)

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/readme.md

Example TOML configuration for DDL workload in 'fixed' mode, specifying tables and rates for DDL operations.

```toml
mode = "fixed"

tables = [
  "test.sbtest1",
  "test.sbtest2",
]

[rate_per_minute]
add_column = 10
drop_column = 10
add_index = 5
drop_index = 5
truncate_table = 1
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/pingcap/ticdc/blob/master/CONTRIBUTING.md

Follow this convention for commit messages to clearly indicate what changed and why. The subject line should be concise, followed by a blank line, and then a more detailed explanation.

```shell
maintainer: add comment for variable declaration

Improve documentation.
```

--------------------------------

### Run Kafka Integration Tests in Docker

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/README.md

Execute Kafka integration tests within a Docker environment. Specify the starting test case if needed. This command requires access to the PingCAP intranet by default.

```bash
START_AT="clustered_index" make kafka_docker_integration_test_with_build

```

--------------------------------

### Create Changefeed via CLI (Kafka Debezium Protocol)

Source: https://context7.com/pingcap/ticdc/llms.txt

CLI command to create a changefeed replicating to Kafka using the Debezium protocol. Specify the PD address, changefeed ID, Kafka sink URI, and optionally a start timestamp.

```bash
./cdc cli changefeed create \
  --pd="http://pd-host:2379" \
  --changefeed-id="cf-debezium" \
  --sink-uri="kafka://broker:9092/debezium-topic?protocol=debezium" \
  --start-ts=0
```

--------------------------------

### Get all tables for a config

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves all tables (eligible, ineligible, and all) that match the specified replica configuration and filter rules, without performing sink verification.

```APIDOC
## POST /api/v2/get_all_tables — Get all tables for a config

### Description
Returns all tables (eligible, ineligible, and all) matched by the given replica config and filter rules, without sink verification.

### Method
POST

### Endpoint
/api/v2/get_all_tables

### Request Body
- **start_ts** (integer) - Required - The start timestamp.
- **replica_config** (object) - Required - The replica configuration.
  - **filter** (object) - Optional - Filter rules for tables.
    - **rules** (array) - Optional - A list of filter rules.

### Response
#### Success Response (200)
- **ineligible_tables** (array) - A list of tables that are ineligible.
- **eligible_tables** (array) - A list of tables that are eligible.
- **all_tables** (array) - A list of all matched tables.
```

--------------------------------

### Run Integration Tests with Community Version and Specific Version

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/README.md

Execute integration tests using the community version of TiCDC and a specified version. This command also allows specifying the starting test case.

```bash
BRANCH=master COMMUNITY=true VERSION=v7.0.0 START_AT="clustered_index" make kafka_docker_integration_test_with_build

```

--------------------------------

### Configure S3/Cloud Storage Sink for Changefeed

Source: https://context7.com/pingcap/ticdc/llms.txt

Example of configuring a changefeed to use an S3/Cloud storage sink with specific CSV formatting and cloud storage settings. This includes options for date separators, delimiters, null values, and file management.

```json
{
    "changefeed_id": "cf-s3-csv",
    "sink_uri": "s3://my-bucket/cdc-data?region=us-west-2",
    "replica_config": {
      "filter": { "rules": ["proddb.*"] },
      "sink": {
        "date_separator": "day",
        "enable_partition_separator": true,
        "csv": {
          "delimiter": ",",
          "quote": "\"",
          "null": "\\N",
          "include_commit_ts": true,
          "binary_encoding_method": "base64",
          "output_old_value": false
        },
        "cloud_storage_config": {
          "worker_count": 16,
          "flush_interval": "5s",
          "file_size": 67108864,
          "file_expiration_days": 30,
          "file_cleanup_cron_spec": "0 0 * * *"
        }
      }
    }
  }
```

--------------------------------

### Automated TiCDC Download Script

Source: https://github.com/pingcap/ticdc/blob/master/README.md

A script to automatically detect the OS and architecture, fetch the latest TiCDC version, and download the corresponding binary. Ensure curl is installed.

```bash
# Detect OS and Architecture
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case $ARCH in
    x86_64) ARCH="amd64" ;; 
    aarch64|arm64) ARCH="arm64" ;; 
esac

# Get the latest version tag from GitHub
TICDC_VERSION=$(curl -s https://api.github.com/repos/pingcap/ticdc/releases/latest | grep tag_name | cut -d '"' -f 4)

# Download the package
URL="https://tiup-mirrors.pingcap.com/cdc-${TICDC_VERSION}-${OS}-${ARCH}.tar.gz"
echo "Downloading TiCDC ${TICDC_VERSION} for ${OS}-${ARCH}..."
curl -L -O "$URL"
```

--------------------------------

### Verify Tables for Changefeed Configuration

Source: https://context7.com/pingcap/ticdc/llms.txt

Validate tables eligible for replication based on a ChangefeedConfig without creating a changefeed. Requires sink URI, start timestamp, and replica configuration.

```bash
curl -X POST http://127.0.0.1:8300/api/v2/verify_table \
  -H "Content-Type: application/json" \
  -d '{
    "sink_uri": "mysql://root:pass@127.0.0.1:3306/",
    "start_ts": 0,
    "replica_config": {
      "filter": { "rules": ["mydb.*"] },
      "force_replicate": false
    }
  }'
```

--------------------------------

### Create Changefeed

Source: https://context7.com/pingcap/ticdc/llms.txt

Creates a new changefeed (replication task). This operation validates the start timestamp, checks the GC safepoint, verifies tables, and confirms sink URI reachability. It returns the `ChangeFeedInfo` of the newly created changefeed.

```APIDOC
## POST /api/v2/changefeeds — Create a changefeed

### Description
Creates a new replication task. Validates start TS against current PD TSO, checks GC safepoint, verifies tables, and confirms the sink URI is reachable. Returns the created `ChangeFeedInfo`.

### Method
POST

### Endpoint
/api/v2/changefeeds

### Parameters
#### Request Body
- **changefeed_id** (string) - Required - The unique identifier for the changefeed.
- **sink_uri** (string) - Required - The URI of the downstream sink (e.g., MySQL, Kafka).
- **replica_config** (object) - Optional - Configuration for replication, including filters and sink-specific settings.
  - **filter** (object) - Optional - Rules for filtering tables or databases.
    - **rules** (array of strings) - Optional - List of filter rules (e.g., `"mydb.*"`).
  - **force_replicate** (boolean) - Optional - Whether to force replication even if some conditions are not met.
  - **sink** (object) - Optional - Sink-specific configuration.
    - **protocol** (string) - Optional - The protocol to use for the sink (e.g., `avro`).
    - **schema_registry** (string) - Optional - URL of the schema registry (if using Avro).
    - **kafka_config** (object) - Optional - Kafka-specific configuration.
      - **partition_num** (integer) - Optional - Number of partitions for Kafka topics.
      - **replication_factor** (integer) - Optional - Replication factor for Kafka topics.

### Request Example
```bash
# Replicate all tables in `mydb` to a MySQL downstream
curl -X POST http://127.0.0.1:8300/api/v2/changefeeds \
  -H "Content-Type: application/json" \
  -d '{
    "changefeed_id": "cf-mysql-prod",
    "sink_uri": "mysql://root:password@127.0.0.1:3306/",
    "replica_config": {
      "filter": {
        "rules": ["mydb.*"]
      },
      "force_replicate": false
    }
  }'

# Replicate to Kafka with Avro protocol
curl -X POST http://127.0.0.1:8300/api/v2/changefeeds \
  -H "Content-Type: application/json" \
  -d '{
    "changefeed_id": "cf-kafka-avro",
    "sink_uri": "kafka://127.0.0.1:9092/topic-name?protocol=avro",
    "replica_config": {
      "filter": { "rules": ["testdb.*"] },
      "sink": {
        "protocol": "avro",
        "schema_registry": "http://127.0.0.1:8081",
        "kafka_config": {
          "partition_num": 3,
          "replication_factor": 1
        }
      }
    }
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created changefeed.
- **state** (string) - The current state of the changefeed (e.g., `normal`).
- **checkpoint_ts** (integer) - The checkpoint timestamp.
- **checkpoint_time** (string) - The timestamp when the checkpoint was last updated.
- **sink_uri** (string) - The URI of the sink.
- **start_ts** (integer) - The timestamp from which replication started.
- **create_time** (string) - The timestamp when the changefeed was created.
- **config** (object) - The configuration of the changefeed.

### Response Example
```json
{
  "id": "cf-mysql-prod",
  "state": "normal",
  "checkpoint_ts": 443123456789,
  "checkpoint_time": "2024-01-15T10:00:00.000Z",
  "sink_uri": "mysql://root:xxxxx@127.0.0.1:3306/",
  "start_ts": 443123456789,
  "create_time": "2024-01-15T10:00:00Z",
  "config": { ... }
}
```
```

--------------------------------

### Build the Workload Tool

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/readme.md

Navigate to the tool's directory and run 'make' to build the workload executable. Ensure a Go environment is set up.

```bash
cd tools/workload
make
```

--------------------------------

### Build Main Binary

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Use this command to build the main binary. It's a fundamental step for ensuring the core functionality is intact.

```bash
make cdc
```

--------------------------------

### Prepare Data for Sysbench Workload

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/schema/sysbench/readme.md

Use this command to prepare a sysbench table with a specified number of rows, threads, and batch size. Ensure you replace <host> with your database host.

```bash
./workload -database-host <host> -database-port 4000 \
  -action prepare -database-db-name test \
  -table-count 1 -workload-type sysbench \
  -thread 16 -batch-size 10 \
  -total-row-count 1000000
```

--------------------------------

### Prepare Data for Bank Update Workload

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/schema/bankupdate/readme.md

Use this command to create a table with a specified number of rows and column sizes. Adjust parameters like `-total-row-count` and `-update-large-column-size` as needed.

```bash
./workload -database-host <host> -database-port 4000 \
  -action prepare -database-db-name test \
  -table-count 1 -workload-type bank_update \
  -thread 16 -total-row-count 20000000 \
  -update-large-column-size 4000
```

--------------------------------

### Get raw etcd metadata

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves all CDC-related key-value pairs stored in etcd. This endpoint is intended for diagnostics and debugging purposes only.

```APIDOC
## GET /api/v2/unsafe/metadata — Get raw etcd metadata

### Description
Returns all CDC-related key-value pairs stored in etcd. For diagnostics and debugging only.

### Method
GET

### Endpoint
/api/v2/unsafe/metadata

### Response
#### Success Response (200)
- **key** (string) - The etcd key.
- **value** (string) - The etcd value (often JSON stringified).
```

--------------------------------

### Format Code

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Run this command to format Go, shell, imports, and log style. It ensures code consistency across the project.

```bash
make fmt
```

--------------------------------

### Run Focused Unit Tests by Package

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Use this command to run unit tests for a specific package. This is recommended for changes within the pkg/ directory.

```bash
make unit_test_pkg PKG=./pkg/sink/...
```

--------------------------------

### Get Raw etcd Metadata

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieve all CDC-related key-value pairs stored in etcd. This endpoint is intended for diagnostics and debugging purposes only.

```bash
curl -s http://127.0.0.1:8300/api/v2/unsafe/metadata | jq '.[:3]'
```

--------------------------------

### Get changefeed status

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves the current replication state, checkpoint timestamp, resolved timestamp, and any associated errors or warnings for a changefeed.

```APIDOC
## GET /api/v2/changefeeds/{changefeed_id}/status

### Description
Returns the current replication state, checkpoint TS, resolved TS, and any last error or warning.

### Method
GET

### Endpoint
/api/v2/changefeeds/{changefeed_id}/status

### Parameters
#### Path Parameters
- **changefeed_id** (string) - Required - The ID of the changefeed to get the status for.

### Response
#### Success Response (200)
- **state** (string) - The current state of the changefeed (e.g., "normal", "failed").
- **checkpoint_ts** (integer) - The checkpoint timestamp.
- **resolved_ts** (integer) - The resolved timestamp.
- **last_error** (object | null) - Information about the last error, if any.
  - **addr** (string) - The address of the node where the error occurred.
  - **code** (string) - The error code.
  - **message** (string) - The error message.
- **last_warning** (object | null) - Information about the last warning, if any.
```

--------------------------------

### Prepare Test Binaries for TiCDC Integration Tests

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/README.md

Download TiCDC related binaries for integration tests. Optionally specify version, OS, and architecture. Ensure compatibility with the current TiCDC version.

```bash
make prepare_test_binaries

```

```bash
make prepare_test_binaries community=true ver=v7.0.0 os=linux arch=amd64

```

--------------------------------

### Run Updates for Bank Update Workload

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/schema/bankupdate/readme.md

Execute this command to perform update operations on the prepared data. Configure update behavior using `-percentage-for-update` and `-batch-size`.

```bash
./workload -database-host <host> -database-port 4000 \
  -action update -database-db-name test \
  -table-count 1 -workload-type bank_update \
  -thread 16 -total-row-count 20000000 \
  -percentage-for-update 1.0 -batch-size 20000 \
  -update-large-column-size 4000
```

--------------------------------

### Run Targeted Integration Tests (Kafka)

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Execute integration tests for Kafka with a specific case. Use this when changes affect downstream adapters or sink behavior crossing system boundaries.

```bash
make integration_test_kafka CASE=<name>
```

--------------------------------

### Get Changefeed Status

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves the current replication state, checkpoint timestamp, resolved timestamp, and any associated errors or warnings for a given changefeed.

```bash
curl -s http://127.0.0.1:8300/api/v2/changefeeds/cf-mysql-prod/status | jq .
# {
#   "state": "normal",
#   "checkpoint_ts": 443123456789,
#   "resolved_ts": 443123456789,
#   "last_error": null,
#   "last_warning": null
# }

# Failed changefeed example:
# {
#   "state": "failed",
#   "checkpoint_ts": 443000000000,
#   "resolved_ts": 443000000000,
#   "last_error": {
#     "addr": "10.0.0.1:8301",
#     "code": "CDC:ErrSinkWriteFailed",
#     "message": "..."
#   }
# }
```

--------------------------------

### Get Latest TiCDC Version Tag

Source: https://github.com/pingcap/ticdc/blob/master/README.md

Retrieves the latest version tag of TiCDC from the GitHub API. This is useful for constructing download links.

```bash
# Get the latest version tag from GitHub API
export TICDC_VERSION=$(curl -s https://api.github.com/repos/pingcap/ticdc/releases/latest | grep tag_name | cut -d '"' -f 4)
echo "Latest version is ${TICDC_VERSION}"
```

--------------------------------

### Prepare Data Across Multiple Databases

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/schema/sysbench/readme.md

This command prepares data across multiple databases, distributing the workload evenly. It creates a specified number of databases with a prefix and populates tables within them.

```bash
./workload -database-host 127.0.0.1 -database-port 4000 \
  -action prepare \
  -db-prefix "db" -db-num 10 \
  -table-count 10 -workload-type sysbench \
  -thread 10 -total-row-count 10000000
```

--------------------------------

### Get Node Status (Legacy API)

Source: https://context7.com/pingcap/ticdc/llms.txt

A compatibility alias for `/api/v2/status`, used primarily by TiDB Operator for health checks. It returns the same `ServerStatus` JSON.

```bash
curl -s http://127.0.0.1:8300/status
# Returns same ServerStatus JSON as /api/v2/status
```

--------------------------------

### Run Targeted Integration Tests (Storage)

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Execute integration tests for storage with a specific case. Use this when changes affect downstream adapters or sink behavior crossing system boundaries.

```bash
make integration_test_storage CASE=<name>
```

--------------------------------

### Get Changefeed Detail

Source: https://context7.com/pingcap/ticdc/llms.txt

Fetches detailed information for a specific changefeed, including its configuration, state, checkpoint timestamp, resolved timestamp, and the maintainer's address.

```bash
curl -s http://127.0.0.1:8300/api/v2/changefeeds/cf-mysql-prod | jq .
# {
#   "id": "cf-mysql-prod",
#   "state": "normal",
#   "sink_uri": "mysql://root:xxxxx@127.0.0.1:3306/",
#   "start_ts": 443100000000,
#   "checkpoint_ts": 443123456789,
#   "resolved_ts": 443123456789,
#   "checkpoint_time": "2024-01-15T10:05:00.000Z",

```

--------------------------------

### Run TiCDC Go Application

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/debezium01/README.md

Execute the TiCDC Go application, providing connection strings for MySQL and Kafka.

```bash
go run ./src --db.mysql="root@tcp(127.0.0.1:3306)/{db}?allowNativePasswords=true" --cdc.kafka 127.0.0.1:9094
```

--------------------------------

### Get Raw etcd Debug Info

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieve all CDC etcd keys and values in a human-readable text format. This is useful for verifying cluster state in integration tests.

```bash
curl -s http://127.0.0.1:8300/debug/info
```

--------------------------------

### Get Changefeed Detail

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves the detailed information for a specific changefeed, identified by its ID. This includes its configuration, state, checkpoint timestamp, resolved timestamp, and the address of its maintainer.

```APIDOC
## GET /api/v2/changefeeds/{changefeed_id} — Get changefeed detail

### Description
Returns full `ChangeFeedInfo` including config, state, checkpoint TS, resolved TS, and maintainer address.

### Method
GET

### Endpoint
/api/v2/changefeeds/{changefeed_id}

### Parameters
#### Path Parameters
- **changefeed_id** (string) - Required - The unique identifier of the changefeed to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the changefeed.
- **state** (string) - The current state of the changefeed.
- **sink_uri** (string) - The URI of the sink.
- **start_ts** (integer) - The timestamp from which replication started.
- **checkpoint_ts** (integer) - The timestamp of the last recorded checkpoint.
- **resolved_ts** (integer) - The timestamp of the last resolved event.
- **checkpoint_time** (string) - The time when the checkpoint was last updated.

### Request Example
```bash
curl -s http://127.0.0.1:8300/api/v2/changefeeds/cf-mysql-prod | jq .
```

### Response Example
```json
{
  "id": "cf-mysql-prod",
  "state": "normal",
  "sink_uri": "mysql://root:xxxxx@127.0.0.1:3306/",
  "start_ts": 443100000000,
  "checkpoint_ts": 443123456789,
  "resolved_ts": 443123456789,
  "checkpoint_time": "2024-01-15T10:05:00.000Z"
}
```
```

--------------------------------

### Get raw etcd debug info

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves all CDC etcd keys and values in a human-readable text format. This is primarily used for integration tests to verify the cluster state.

```APIDOC
## GET /debug/info

### Description
Returns all CDC etcd keys and values in human-readable text format. Used in integration tests to verify cluster state.

### Method
GET

### Endpoint
/debug/info

### Response
#### Success Response (200)
- **etcd_info** (string) - Plaintext containing etcd keys and values.
```

--------------------------------

### Get Node Status

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves the status of a TiCDC node, including version, git hash, node ID, cluster ID, PID, coordinator status, and liveness state.

```APIDOC
## GET /api/v2/status — Get node status

### Description
Returns version, git hash, node ID, cluster ID, PID, whether the node is coordinator, and liveness state.

### Method
GET

### Endpoint
/api/v2/status

### Response
#### Success Response (200)
- **version** (string) - The version of TiCDC.
- **git_hash** (string) - The git hash of the TiCDC build.
- **id** (string) - The unique identifier of the node.
- **cluster_id** (string) - The identifier of the TiCDC cluster.
- **pid** (integer) - The process ID of the TiCDC node.
- **is_owner** (boolean) - Indicates if the node is the cluster owner (coordinator).
- **liveness** (integer) - The liveness state of the node (e.g., 0 for alive).

### Request Example
```bash
curl -s http://127.0.0.1:8300/api/v2/status | jq .
```

### Response Example
```json
{
  "version": "v9.0.0",
  "git_hash": "abc123...",
  "id": "6bbc01c8-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "cluster_id": "default",
  "pid": 12345,
  "is_owner": true,
  "liveness": 0
}
```
```

--------------------------------

### Create Changefeed via CLI (MySQL Sink)

Source: https://context7.com/pingcap/ticdc/llms.txt

Use the CLI to create a changefeed that replicates data to a MySQL database. This command requires specifying the PD address, changefeed ID, sink URI, and an optional configuration file for filters and dispatchers.

```bash
./cdc cli changefeed create \
  --pd="http://pd-host:2379" \
  --changefeed-id="cf-mysql-prod" \
  --sink-uri="mysql://root:password@mysql-host:3306/" \
  --config=changefeed.toml
```

```toml
# [filter]
# rules = ['mydb.*']
#
# [sink]
# dispatchers = [
#   {matcher = ['mydb.orders'], partition = "rowid"},
# ]
```

--------------------------------

### Run Targeted Integration Tests (MySQL)

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Execute integration tests for MySQL with a specific case. Use this when changes affect downstream adapters or sink behavior crossing system boundaries.

```bash
make integration_test_mysql CASE=<name>
```

--------------------------------

### Get Node Status (API v2)

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves the status of a TiCDC node, including version, git hash, and cluster information. Use this to verify node health and configuration.

```bash
curl -s http://127.0.0.1:8300/api/v2/status | jq .
# Expected response:
# {
#   "version": "v9.0.0",
#   "git_hash": "abc123...",
#   "id": "6bbc01c8-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
#   "cluster_id": "default",
#   "pid": 12345,
#   "is_owner": true,
#   "liveness": 0
# }
```

--------------------------------

### Run Targeted Integration Tests (Pulsar)

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Execute integration tests for Pulsar with a specific case. Use this when changes affect downstream adapters or sink behavior crossing system boundaries.

```bash
make integration_test_pulsar CASE=<name>
```

--------------------------------

### List Processors (Compatibility Stub)

Source: https://context7.com/pingcap/ticdc/llms.txt

Returns an empty list. This endpoint is implemented for API compatibility with older TiCDC architectures and is not used in the new architecture.

```bash
curl -s http://127.0.0.1:8300/api/v2/processors
```

--------------------------------

### List All Changefeeds

Source: https://context7.com/pingcap/ticdc/llms.txt

Retrieves a paginated list of all changefeeds. Supports filtering by `state` (e.g., `normal`, `stopped`, `failed`) and `keyspace` for multi-tenant environments.

```bash
curl -s http://127.0.0.1:8300/api/v2/changefeeds | jq .
# {
#   "total": 2,
#   "items": [
#     {
#       "id": "cf-mysql-prod",
#       "state": "normal",
#       "checkpoint_tso": 443123456789,
#       "checkpoint_time": "2024-01-15T10:05:00.000Z",
#       "error": null
#     },
#     ...
#   ]
# }
```

```bash
curl -s "http://127.0.0.1:8300/api/v2/changefeeds?state=stopped"
```

```bash
curl -s "http://127.0.0.1:8300/api/v2/changefeeds?keyspace=myks"
```

--------------------------------

### Run Pre-submit Checks

Source: https://github.com/pingcap/ticdc/blob/master/docs/agents/validation.md

Execute all pre-submit checks with this command. This is a comprehensive check before submitting code.

```bash
make check
```

--------------------------------

### Create a changefeed with comprehensive replica config

Source: https://context7.com/pingcap/ticdc/llms.txt

Creates a new changefeed with a detailed replication configuration, including filtering, sink settings, and scheduler options.

```APIDOC
## POST /api/v2/changefeeds

### Description
Creates a new changefeed with the specified configuration.

### Method
POST

### Endpoint
/api/v2/changefeeds

#### Request Body
- **changefeed_id** (string) - Required - The unique identifier for the changefeed.
- **sink_uri** (string) - Required - The URI for the sink.
- **replica_config** (object) - Optional - The replication configuration for the changefeed.
  - **memory_quota** (integer) - Optional - Memory quota for the changefeed.
  - **case_sensitive** (boolean) - Optional - Whether table names are case-sensitive.
  - **force_replicate** (boolean) - Optional - Force replication of tables.
  - **ignore_ineligible_table** (boolean) - Optional - Ignore tables that are not eligible for replication.
  - **enable_sync_point** (boolean) - Optional - Enable sync points.
  - **filter** (object) - Optional - Filtering rules for replication.
    - **rules** (array of strings) - Optional - List of include/exclude rules.
    - **ignore_ineligible_table** (boolean) - Optional - Ignore tables that are not eligible for replication.
    - **ignore_txn_start_ts** (array of integers) - Optional - Transaction start timestamps to ignore.
    - **event_filters** (array of objects) - Optional - Filters for specific events.
      - **matcher** (array of strings) - Optional - Matchers for tables or databases.
      - **ignore_event** (array of strings) - Optional - Events to ignore (e.g., "delete").
      - **ignore_sql** (array of strings) - Optional - SQL statements to ignore.
  - **sink** (object) - Optional - Sink-specific configuration.
    - **protocol** (string) - Optional - The protocol for the sink (e.g., "canal-json").
    - **dispatchers** (array of objects) - Optional - Rules for dispatching change events.
      - **matcher** (array of strings) - Optional - Matchers for tables or databases.
      - **partition** (string) - Optional - Partitioning strategy.
      - **topic** (string) - Optional - The topic name.
    - **kafka_config** (object) - Optional - Kafka-specific configuration.
      - **partition_num** (integer) - Optional - Number of Kafka partitions.
      - **replication_factor** (integer) - Optional - Kafka replication factor.
      - **compression** (string) - Optional - Compression type (e.g., "lz4").
      - **required_acks** (integer) - Optional - Kafka required acknowledgments.
  - **scheduler** (object) - Optional - Scheduler configuration.
    - **enable_table_across_nodes** (boolean) - Optional - Enable table replication across nodes.
    - **region_threshold** (integer) - Optional - Threshold for region splitting.
  - **changefeed_error_stuck_duration** (integer) - Optional - Duration to consider a changefeed stuck due to errors.

### Request Example
```json
{
  "changefeed_id": "cf-full-config",
  "sink_uri": "kafka://broker:9092/topic?protocol=canal-json",
  "replica_config": {
    "memory_quota": 1073741824,
    "case_sensitive": false,
    "force_replicate": false,
    "ignore_ineligible_table": true,
    "enable_sync_point": false,
    "filter": {
      "rules": ["db1.*", "db2.orders", "!db2.tmp_*"],
      "ignore_txn_start_ts": [],
      "event_filters": [
        {
          "matcher": ["db1.audit_log"],
          "ignore_event": ["delete"],
          "ignore_sql": ["^DROP"]
        }
      ]
    },
    "sink": {
      "protocol": "canal-json",
      "dispatchers": [
        {
          "matcher": ["db1.*"],
          "partition": "ts",
          "topic": "db1-changes"
        }
      ],
      "kafka_config": {
        "partition_num": 6,
        "replication_factor": 3,
        "compression": "lz4",
        "required_acks": -1
      }
    },
    "scheduler": {
      "enable_table_across_nodes": true,
      "region_threshold": 10000
    },
    "changefeed_error_stuck_duration": 1800000000000
  }
}
```
```

--------------------------------

### Version Negotiation Flow Diagram

Source: https://github.com/pingcap/ticdc/blob/master/docs/design/2025-11-09-ticdc-event-encoding-architecture.md

Illustrates the process of version negotiation between a V2 sender and a V1 receiver, including error handling and fallback mechanisms.

```text
┌──────────────┐                              ┌──────────────┐
│   Sender     │                              │   Receiver   │
│  (V2 Code)   │                              │  (V1 Code)   │
└──────┬───────┘                              └──────┬───────┘
       │                                             │
       │  1. Marshal Event with V2 Format           │
       │     [Header: Type=3, Ver=2, Len=100]       │
       │     + V2 Payload                           │
       ├────────────────────────────────────────────>│
       │                                             │
       │                                             │ 2. UnmarshalEventHeader()
       │                                             │    - Read Header: Ver=2
       │                                             │
       │                                             │ 3. Version Check
       │                                             │    switch version {
       │                                             │      case V0: ✓
       │                                             │      case V1: ✓
       │                                             │      case V2: ✗ (Not Supported)
       │                                             │    }
       │                                             │
       │  4. Error: "unsupported version: 2"        │
       │<────────────────────────────────────────────┤
       │                                             │
       │  5. Sender Fallback to V1                  │
       │     [Header: Type=3, Ver=1, Len=80]        │
       │     + V1 Payload                           │
       ├────────────────────────────────────────────>│
       │                                             │
       │                                             │ 6. Decode V1 Successfully ✓
       │                                             │

```

--------------------------------

### Create TiCDC Changefeed

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/debezium01/README.md

Create a TiCDC changefeed using the tiup cdc cli, specifying the server, configuration file, and Kafka sink URI.

```bash
tiup cdc cli changefeed create -c test \
  --server=http://127.0.0.1:8300 --config changefeed.toml \
  --sink-uri="kafka://127.0.0.1:9094/output_ticdc?protocol=debezium"
```

--------------------------------

### Patch TiCDC Nodes with New Binary

Source: https://github.com/pingcap/ticdc/blob/master/README.md

Demonstrates patching existing TiCDC nodes with a new binary and enabling the new architecture. Requires tiup cluster and a configuration file.

```bash
# Scale out some old version TiCDC nodes, if you don't already have some
tiup cluster scale-out test-cluster scale-out.yml

#scale-out.yml
#cdc_servers:
#  - host: 172.31.10.1

# Patch the download binary to the cluster
tiup cluster patch --overwrite test-cluster cdc-${TICDC_VERSION}-linux-amd64.tar.gz -R cdc

# Enable TiCDC new architecture by setting the "newarch" parameter
tiup cluster edit-config test-cluster
#cdc_servers:
# ...
# config:
#    newarch: true

tiup cluster reload test-cluster -R cdc
```

--------------------------------

### Run DDL Workload

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/readme.md

Execute DDL operations based on a TOML configuration file. Specify database connection details and DDL-specific parameters.

```bash
./bin/workload -action ddl \
    -database-host 127.0.0.1 \
    -database-port 4000 \
    -database-db-name test \
    -ddl-config ./ddl.toml \
    -ddl-worker 1 \
    -ddl-timeout 2m
```

--------------------------------

### Run Updates on Sysbench Workload

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/schema/sysbench/readme.md

Execute updates on the sysbench table, specifying the percentage of threads for updates and the number of update ranges. Replace <host> with your database host.

```bash
./workload -database-host <host> -database-port 4000 \
  -action update -database-db-name test \
  -table-count 1 -workload-type sysbench \
  -thread 16 -percentage-for-update 1.0 \
  -range-num 5
```

--------------------------------

### Create Debezium Kafka Connector

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/debezium01/README.md

Use curl to POST a JSON configuration to the Debezium Kafka Connect API to create a new MySQL connector.

```bash
curl -i -X POST \
  -H "Accept:application/json" \
  -H "Content-Type:application/json" \
  localhost:8083/connectors/ --data-binary @- << EOF
{
  "name": "my-connector",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "tasks.max": "1",
    "database.hostname": "mysql",
    "database.port": "3306",
    "database.user": "debezium",
    "database.password": "dbz",
    "database.server.id": "184054",
    "topic.prefix": "default",
    "schema.history.internal.kafka.bootstrap.servers": "kafka:9092",
    "schema.history.internal.kafka.topic": "schemahistory.test",
    "transforms": "x",
    "transforms.x.type": "org.apache.kafka.connect.transforms.RegexRouter",
    "transforms.x.regex": "(.*)",
    "transforms.x.replacement":"output_debezium",
    "binary.handling.mode": "base64",
    "decimal.handling.mode": "double"
  }
}
EOF
```

--------------------------------

### List processors (compatibility stub)

Source: https://context7.com/pingcap/ticdc/llms.txt

Returns an empty list. This endpoint is implemented for API compatibility with the older TiCDC architecture and does not reflect active processors in the new architecture.

```APIDOC
## GET /api/v2/processors — List processors (compatibility stub)

### Description
Returns an empty list. Implemented for API compatibility with the old TiCDC architecture only — processors are not used in the new architecture.

### Method
GET

### Endpoint
/api/v2/processors

### Response
#### Success Response (200)
- **total** (integer) - The total number of processors (always 0).
- **items** (array) - An empty list.
```

--------------------------------

### Create Changefeed to Kafka with Avro

Source: https://context7.com/pingcap/ticdc/llms.txt

Creates a TiCDC changefeed replicating data from `testdb` to Kafka using the Avro protocol. Requires specifying the `schema_registry` and Kafka configuration details.

```bash
curl -X POST http://127.0.0.1:8300/api/v2/changefeeds \
  -H "Content-Type: application/json" \
  -d '{
    "changefeed_id": "cf-kafka-avro",
    "sink_uri": "kafka://127.0.0.1:9092/topic-name?protocol=avro",
    "replica_config": {
      "filter": { "rules": ["testdb.*"] },
      "sink": {
        "protocol": "avro",
        "schema_registry": "http://127.0.0.1:8081",
        "kafka_config": {
          "partition_num": 3,
          "replication_factor": 1
        }
      }
    }
  }'
```

--------------------------------

### Run MySQL Integration Tests in Docker

Source: https://github.com/pingcap/ticdc/blob/master/tests/integration_tests/README.md

Execute MySQL integration tests within a Docker environment. Specify the test case to run. This command requires access to the PingCAP intranet by default.

```bash
CASE="clustered_index" make mysql_docker_integration_test_with_build

```

--------------------------------

### Insert, Update, and DDL Together

Source: https://github.com/pingcap/ticdc/blob/master/tools/workload/readme.md

Combine insert and update operations with concurrent DDL execution. Set `-percentage-for-delete 0` to exclude delete operations.

```bash
./bin/workload -action write \
    -database-host 127.0.0.1 \
    -database-port 4000 \
    -database-db-name db1 \
    -table-count 1000 \
    -workload-type sysbench \
    -thread 32 \
    -batch-size 64 \
    -percentage-for-update 0.5 \
    -percentage-for-delete 0 \
    -ddl-config ./ddl.toml \
    -ddl-worker 1 \
    -ddl-timeout 2m
```