You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by li...@apache.org on 2026/06/28 14:32:21 UTC
(seatunnel) branch dev updated: [Feature][Connector-V2] Add Vitess CDC source connector (#11059)
This is an automated email from the ASF dual-hosted git repository.
davidzollo pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 71ab292daf [Feature][Connector-V2] Add Vitess CDC source connector (#11059)
71ab292daf is described below
commit 71ab292dafe821d08306434456551a8aebce5999
Author: Daniel <es...@outlook.com>
AuthorDate: Sun Jun 28 22:32:14 2026 +0800
[Feature][Connector-V2] Add Vitess CDC source connector (#11059)
---
config/plugin_config | 3 +-
.../connectors/changelog/connector-cdc-vitess.md | 7 +
docs/en/connectors/source/Vitess-CDC.md | 148 +++++++
.../connectors/changelog/connector-cdc-vitess.md | 7 +
docs/zh/connectors/source/Vitess-CDC.md | 145 +++++++
plugin-mapping.properties | 1 +
.../cdc/base/utils/SourceRecordUtils.java | 20 +-
.../cdc/base/utils/SourceRecordUtilsTest.java | 45 +++
.../connector-cdc/connector-cdc-vitess/pom.xml | 101 +++++
.../cdc/vitess/config/VitessSourceConfig.java | 259 +++++++++++++
.../cdc/vitess/config/VitessSourceOptions.java | 144 +++++++
.../seatunnel/cdc/vitess/source/VitessSource.java | 84 ++++
.../cdc/vitess/source/VitessSourceFactory.java | 252 ++++++++++++
.../source/enumerator/VitessSourceEnumerator.java | 119 ++++++
.../enumerator/VitessSourceEnumeratorState.java | 54 +++
.../vitess/source/reader/VitessSourceReader.java | 379 ++++++++++++++++++
.../cdc/vitess/source/split/VitessSourceSplit.java | 159 ++++++++
.../source/split/VitessTableSchemaState.java | 250 ++++++++++++
.../cdc/vitess/source/VitessSourceFactoryTest.java | 387 ++++++++++++++++++
.../source/reader/TestVitessSourceReaderIT.java | 431 +++++++++++++++++++++
.../cdc/vitess/source/reader/VitessContainer.java | 90 +++++
seatunnel-connectors-v2/connector-cdc/pom.xml | 1 +
seatunnel-dist/pom.xml | 6 +
23 files changed, 3088 insertions(+), 4 deletions(-)
diff --git a/config/plugin_config b/config/plugin_config
index 5f560a4a46..3e7846976d 100644
--- a/config/plugin_config
+++ b/config/plugin_config
@@ -30,6 +30,7 @@ connector-cdc-sqlserver
connector-cdc-postgres
connector-cdc-oracle
connector-cdc-tidb
+connector-cdc-vitess
connector-clickhouse
connector-datahub
connector-databend
@@ -102,4 +103,4 @@ connector-sensorsdata
connector-hugegraph
connector-lance
connector-mqtt
-connector-bigquery
\ No newline at end of file
+connector-bigquery
diff --git a/docs/en/connectors/changelog/connector-cdc-vitess.md b/docs/en/connectors/changelog/connector-cdc-vitess.md
new file mode 100644
index 0000000000..2c65ae6713
--- /dev/null
+++ b/docs/en/connectors/changelog/connector-cdc-vitess.md
@@ -0,0 +1,7 @@
+<details><summary> Change Log </summary>
+
+| Change | Commit | Version |
+| --- | --- | --- |
+|[Feature][Connector-V2][CDC] Add Vitess CDC source connector|-|Next|
+
+</details>
diff --git a/docs/en/connectors/source/Vitess-CDC.md b/docs/en/connectors/source/Vitess-CDC.md
new file mode 100644
index 0000000000..de9573c3f2
--- /dev/null
+++ b/docs/en/connectors/source/Vitess-CDC.md
@@ -0,0 +1,148 @@
+import ChangeLog from '../changelog/connector-cdc-vitess.md';
+
+# Vitess CDC
+
+> Vitess CDC source connector
+
+## Support Those Engines
+
+> SeaTunnel Zeta<br/>
+> Flink <br/>
+
+## Description
+
+The Vitess CDC connector captures change events from Vitess VTGate through the VStream gRPC API.
+The first delivery keeps the connector intentionally narrow:
+
+- streaming only, no initial snapshot phase
+- explicit schema metadata only, provided through `schema` or `tables_configs`
+- optional `table-names` / `table-pattern` filters over those declared schemas
+- checkpoint / restore based on serialized Vitess VGTID state
+- rows emitted as SeaTunnel CDC rows for existing multi-table downstream paths
+
+If you need a reproducible bootstrap position, use `startup.mode = SPECIFIC` with a concrete
+Vitess VGTID. `LATEST` is provided as a convenience startup mode aligned with existing Vitess CDC
+backends, but its initial position is symbolic until the first CDC event materializes a concrete
+offset.
+
+## Key features
+
+- [ ] [batch](../../introduction/concepts/connector-v2-features.md)
+- [x] [stream](../../introduction/concepts/connector-v2-features.md)
+- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md)
+- [ ] [column projection](../../introduction/concepts/connector-v2-features.md)
+- [ ] [parallelism](../../introduction/concepts/connector-v2-features.md)
+- [ ] [support user-defined split](../../introduction/concepts/connector-v2-features.md)
+
+## Supported DataSource Info
+
+| Datasource | Supported versions | Driver | Url | Maven |
+| --- | --- | --- | --- | --- |
+| Vitess VTGate VStream | VTGate deployments compatible with Debezium Vitess 1.9.8.Final | gRPC client built into the connector | `hostname` + `port` | https://mvnrepository.com/artifact/io.debezium/debezium-connector-vitess/1.9.8.Final |
+
+## Using Dependency
+
+No JDBC driver is required for the connector runtime itself because CDC traffic is read through
+VTGate gRPC. If you use JDBC for verification or downstream examples, add the MySQL JDBC driver
+separately.
+
+## Source Options
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| hostname | String | Yes | - | Hostname or IP address of the Vitess VTGate gRPC server. |
+| port | Int | No | 15991 | Port of the Vitess VTGate gRPC server. |
+| keyspace | String | Yes | - | Vitess keyspace captured by the connector. |
+| schema | Config | Yes* | - | Single-table schema definition. The schema block must provide `table` plus either `columns` or `metadata_table_id`. |
+| tables_configs | List\<Map\> | Yes* | - | Multi-table schema definitions. Each entry must contain a `schema` block with `table` plus either `columns` or `metadata_table_id`. |
+| table-names | List | No** | - | Optional database-qualified tables to capture from the declared schema set, for example `commerce.orders`. |
+| table-pattern | String | No** | - | Optional regular expression used to filter the declared schema set. |
+| metalake_type | Enum | No | GRAVITINO | Metadata lake implementation used when a schema block resolves columns through `metadata_table_id`. |
+| startup.mode | Enum | No | LATEST | Supported values are `latest` and `specific`. `specific` is the stable startup mode for reproducible restore. |
+| startup.specific-offset.vgtid | String | No | - | Vitess VGTID used when `startup.mode = specific`. |
+| tablet-type | Enum | No | MASTER | VTGate tablet type used by VStream. Supported values are `MASTER`, `REPLICA`, `RDONLY`. |
+| shard | String | No | - | Optional shard restriction. Omit it to capture all shards in the keyspace. |
+| stop-on-reshard | Boolean | No | false | Whether the connector should stop after resharding. |
+| keepalive.interval.ms | Long | No | Long.MAX_VALUE | gRPC keepalive interval in milliseconds. |
+| grpc.headers | String | No | - | Optional comma-separated gRPC headers in `key:value` format. |
+| grpc.max-inbound-message-size | Int | No | 4194304 | Maximum inbound gRPC message size in bytes. |
+| server-time-zone | String | No | UTC | Time zone used by SeaTunnel row deserialization. |
+| format | Enum | No | DEFAULT | Optional output format. Supported values are `DEFAULT` and `COMPATIBLE_DEBEZIUM_JSON`. |
+| debezium | Config | No | - | Pass-through Debezium properties for the Vitess connector backend. |
+
+\* Configure exactly one of `schema` and `tables_configs`.
+
+\** Configure at most one of `table-names` and `table-pattern`. When both are omitted, the connector captures every declared schema table.
+
+## Notes
+
+- The first delivery does not read an initial table snapshot.
+- Dynamic discovery of newly added tables is out of scope.
+- Schema evolution events are not emitted in this first delivery.
+- Restore uses the checkpointed SeaTunnel table schema snapshot instead of re-parsing the latest config shape.
+- A focused integration path is provided by `TestVitessSourceReaderIT`, which runs against
+ `vitess/vttestserver`.
+
+## Task Example
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "STREAMING"
+ checkpoint.interval = 5000
+}
+
+source {
+ Vitess-CDC {
+ plugin_output = "vitess_cdc"
+ hostname = "127.0.0.1"
+ port = 15992
+ keyspace = "test"
+ tables_configs = [
+ {
+ schema = {
+ table = "test.products"
+ columns = [
+ { name = "id", type = "int" }
+ { name = "name", type = "string" }
+ { name = "description", type = "string" }
+ { name = "weight", type = "float" }
+ ]
+ primaryKey = {
+ name = "pk_products"
+ columnNames = ["id"]
+ }
+ }
+ },
+ {
+ schema = {
+ table = "test.customers"
+ columns = [
+ { name = "id", type = "int" }
+ { name = "name", type = "string" }
+ ]
+ primaryKey = {
+ name = "pk_customers"
+ columnNames = ["id"]
+ }
+ }
+ }
+ ]
+ table-names = ["test.products", "test.customers"]
+ startup.mode = "specific"
+ startup.specific-offset.vgtid = "[{\"keyspace\":\"test\",\"shard\":\"-\",\"gtid\":\"MySQL56/uuid:1-200\"}]"
+ server-time-zone = "UTC"
+ }
+}
+
+transform {
+}
+
+sink {
+ Console {}
+}
+```
+
+## Changelog
+
+<ChangeLog />
diff --git a/docs/zh/connectors/changelog/connector-cdc-vitess.md b/docs/zh/connectors/changelog/connector-cdc-vitess.md
new file mode 100644
index 0000000000..312cdfa756
--- /dev/null
+++ b/docs/zh/connectors/changelog/connector-cdc-vitess.md
@@ -0,0 +1,7 @@
+<details><summary> Change Log </summary>
+
+| 变更 | Commit | 版本 |
+| --- | --- | --- |
+|[Feature][Connector-V2][CDC] 新增 Vitess CDC Source 连接器|-|Next|
+
+</details>
diff --git a/docs/zh/connectors/source/Vitess-CDC.md b/docs/zh/connectors/source/Vitess-CDC.md
new file mode 100644
index 0000000000..67a3aa065f
--- /dev/null
+++ b/docs/zh/connectors/source/Vitess-CDC.md
@@ -0,0 +1,145 @@
+import ChangeLog from '../changelog/connector-cdc-vitess.md';
+
+# Vitess CDC
+
+> Vitess CDC Source 连接器
+
+## 支持的引擎
+
+> SeaTunnel Zeta<br/>
+> Flink <br/>
+
+## 描述
+
+Vitess CDC 连接器通过 VTGate 的 VStream gRPC API 订阅变更事件。第一版交付范围刻意收窄,只覆盖一条可复现、可恢复的 CDC 路径:
+
+- 仅支持流式 CDC,不包含初始快照阶段
+- 必须通过 `schema` 或 `tables_configs` 显式提供表结构
+- `table-names` / `table-pattern` 只作为这些已声明表结构的可选过滤条件
+- 基于序列化后的 Vitess VGTID 接入 SeaTunnel checkpoint / restore
+- 输出 SeaTunnel CDC 行,兼容现有多表下游链路
+
+如果你需要可复现的启动位点,请使用 `startup.mode = SPECIFIC` 并提供明确的
+Vitess VGTID。`LATEST` 作为便捷启动模式保留,但在第一条 CDC 事件落地成具体 offset
+之前,它的初始位置仍然是符号化的 `current`。
+
+## 主要功能
+
+- [ ] [批处理](../../introduction/concepts/connector-v2-features.md)
+- [x] [流处理](../../introduction/concepts/connector-v2-features.md)
+- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md)
+- [ ] [column projection](../../introduction/concepts/connector-v2-features.md)
+- [ ] [并行度](../../introduction/concepts/connector-v2-features.md)
+- [ ] [支持用户定义的拆分](../../introduction/concepts/connector-v2-features.md)
+
+## 支持的数据源信息
+
+| 数据源 | 支持版本 | 驱动 | 地址形式 | Maven |
+| --- | --- | --- | --- | --- |
+| Vitess VTGate VStream | 与 Debezium Vitess 1.9.8.Final 兼容的 VTGate 部署 | 连接器内置 gRPC 客户端 | `hostname` + `port` | https://mvnrepository.com/artifact/io.debezium/debezium-connector-vitess/1.9.8.Final |
+
+## 依赖说明
+
+连接器运行时本身不依赖 JDBC 驱动,因为 CDC 数据通过 VTGate gRPC 获取。如果你需要用
+JDBC 做验证或示例下游,请额外准备 MySQL JDBC 驱动。
+
+## 源选项
+
+| 名称 | 类型 | 必填 | 默认值 | 描述 |
+| --- | --- | --- | --- | --- |
+| hostname | String | 是 | - | Vitess VTGate gRPC 服务地址。 |
+| port | Int | 否 | 15991 | Vitess VTGate gRPC 端口。 |
+| keyspace | String | 是 | - | 当前连接器采集的 Vitess keyspace。 |
+| schema | Config | 是* | - | 单表 schema 定义。schema 中必须提供 `table`,并且至少提供 `columns` 或 `metadata_table_id` 之一。 |
+| tables_configs | List\<Map\> | 是* | - | 多表 schema 定义列表。每个元素都必须包含一个 `schema` 块,且其中必须提供 `table`,并至少提供 `columns` 或 `metadata_table_id` 之一。 |
+| table-names | List | 否** | - | 从已声明 schema 集合里筛选要采集的表,表名必须带数据库前缀,例如 `commerce.orders`。 |
+| table-pattern | String | 否** | - | 用于筛选已声明 schema 集合的表名正则,表名必须带数据库前缀。 |
+| metalake_type | Enum | 否 | GRAVITINO | 当 schema 通过 `metadata_table_id` 从元数据中心解析列定义时使用的 metadata lake 实现。 |
+| startup.mode | Enum | 否 | LATEST | 仅支持 `latest` 和 `specific`。其中 `specific` 是可复现恢复的稳定启动模式。 |
+| startup.specific-offset.vgtid | String | 否 | - | 当 `startup.mode = specific` 时使用的 Vitess VGTID。 |
+| tablet-type | Enum | 否 | MASTER | VStream 使用的 tablet 类型,支持 `MASTER`、`REPLICA`、`RDONLY`。 |
+| shard | String | 否 | - | 可选 shard 限定。不配置时会采集 keyspace 的全部 shard。 |
+| stop-on-reshard | Boolean | 否 | false | reshard 后是否停止当前采集。 |
+| keepalive.interval.ms | Long | 否 | Long.MAX_VALUE | gRPC keepalive 间隔,单位毫秒。 |
+| grpc.headers | String | 否 | - | 可选 gRPC headers,格式为 `key:value,key2:value2`。 |
+| grpc.max-inbound-message-size | Int | 否 | 4194304 | 允许接收的最大 gRPC 消息大小,单位字节。 |
+| server-time-zone | String | 否 | UTC | SeaTunnel 行反序列化使用的时区。 |
+| format | Enum | 否 | DEFAULT | 输出格式,支持 `DEFAULT` 和 `COMPATIBLE_DEBEZIUM_JSON`。 |
+| debezium | Config | 否 | - | 透传给 Debezium Vitess 后端的附加参数。 |
+
+\* `schema` 和 `tables_configs` 二选一,必须提供其中之一。
+
+\** `table-names` 和 `table-pattern` 至多配置一个;如果都不配,则采集所有已声明 schema 的表。
+
+## 说明
+
+- 第一版不支持初始快照读取。
+- 第一版不支持运行时动态发现新表。
+- 第一版不发送 schema evolution 事件。
+- restore 时会优先使用 checkpoint 中保存的 SeaTunnel 表结构快照,而不是重新按最新配置重建字段列表。
+- 仓库内提供了 `TestVitessSourceReaderIT` 作为真实可跑的集成验证路径,底层使用
+ `vitess/vttestserver`。
+
+## 任务示例
+
+```hocon
+env {
+ parallelism = 1
+ job.mode = "STREAMING"
+ checkpoint.interval = 5000
+}
+
+source {
+ Vitess-CDC {
+ plugin_output = "vitess_cdc"
+ hostname = "127.0.0.1"
+ port = 15992
+ keyspace = "test"
+ tables_configs = [
+ {
+ schema = {
+ table = "test.products"
+ columns = [
+ { name = "id", type = "int" }
+ { name = "name", type = "string" }
+ { name = "description", type = "string" }
+ { name = "weight", type = "float" }
+ ]
+ primaryKey = {
+ name = "pk_products"
+ columnNames = ["id"]
+ }
+ }
+ },
+ {
+ schema = {
+ table = "test.customers"
+ columns = [
+ { name = "id", type = "int" }
+ { name = "name", type = "string" }
+ ]
+ primaryKey = {
+ name = "pk_customers"
+ columnNames = ["id"]
+ }
+ }
+ }
+ ]
+ table-names = ["test.products", "test.customers"]
+ startup.mode = "specific"
+ startup.specific-offset.vgtid = "[{\"keyspace\":\"test\",\"shard\":\"-\",\"gtid\":\"MySQL56/uuid:1-200\"}]"
+ server-time-zone = "UTC"
+ }
+}
+
+transform {
+}
+
+sink {
+ Console {}
+}
+```
+
+## 变更日志
+
+<ChangeLog />
diff --git a/plugin-mapping.properties b/plugin-mapping.properties
index 5e0a4460ce..838c9fa4d4 100644
--- a/plugin-mapping.properties
+++ b/plugin-mapping.properties
@@ -115,6 +115,7 @@ seatunnel.sink.Maxcompute = connector-maxcompute
seatunnel.source.MySQL-CDC = connector-cdc-mysql
seatunnel.source.MongoDB-CDC = connector-cdc-mongodb
seatunnel.source.TiDB-CDC = connector-cdc-tidb
+seatunnel.source.Vitess-CDC = connector-cdc-vitess
seatunnel.sink.S3Redshift = connector-s3-redshift
seatunnel.source.Web3j = connector-web3j
seatunnel.source.TDengine = connector-tdengine
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtils.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtils.java
index 7237d99dbc..3d9f2a25f0 100644
--- a/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtils.java
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtils.java
@@ -38,7 +38,6 @@ import java.sql.SQLException;
import java.util.Arrays;
import java.util.List;
-import static io.debezium.connector.AbstractSourceInfo.DATABASE_NAME_KEY;
import static io.debezium.connector.AbstractSourceInfo.SCHEMA_NAME_KEY;
import static io.debezium.connector.AbstractSourceInfo.TABLE_NAME_KEY;
@@ -123,7 +122,7 @@ public class SourceRecordUtils {
public static TableId getTableId(SourceRecord dataRecord) {
Struct value = (Struct) dataRecord.value();
Struct source = value.getStruct(Envelope.FieldName.SOURCE);
- String dbName = source.getString(DATABASE_NAME_KEY);
+ String dbName = resolveDatabaseName(source);
// Oracle need schemaName
String schemaName = getSchemaName(source);
String tableName = source.getString(TABLE_NAME_KEY);
@@ -214,7 +213,7 @@ public class SourceRecordUtils {
public static TablePath getTablePath(SourceRecord record) {
Struct messageStruct = (Struct) record.value();
Struct sourceStruct = messageStruct.getStruct(Envelope.FieldName.SOURCE);
- String databaseName = sourceStruct.getString(AbstractSourceInfo.DATABASE_NAME_KEY);
+ String databaseName = resolveDatabaseName(sourceStruct);
String tableName = sourceStruct.getString(AbstractSourceInfo.TABLE_NAME_KEY);
String schemaName = null;
if (sourceStruct.schema().field(AbstractSourceInfo.SCHEMA_NAME_KEY) != null) {
@@ -223,6 +222,21 @@ public class SourceRecordUtils {
return TablePath.of(databaseName, schemaName, tableName);
}
+ /**
+ * Resolves the logical database name from Debezium source metadata.
+ *
+ * <p>Vitess writes an empty string into the generic database field and stores the real logical
+ * database in {@code keyspace}, so blank values must also trigger the fallback.
+ */
+ private static String resolveDatabaseName(Struct sourceStruct) {
+ String databaseName = sourceStruct.getString(AbstractSourceInfo.DATABASE_NAME_KEY);
+ if ((databaseName == null || databaseName.isEmpty())
+ && sourceStruct.schema().field("keyspace") != null) {
+ return sourceStruct.getString("keyspace");
+ }
+ return databaseName;
+ }
+
public static String getDdl(SourceRecord record) {
Struct schemaChangeStruct = (Struct) record.value();
return schemaChangeStruct.getString(HistoryRecord.Fields.DDL_STATEMENTS);
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/test/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtilsTest.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/test/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtilsTest.java
index 3b1fceb900..d481f49981 100644
--- a/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/test/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtilsTest.java
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/test/java/org/apache/seatunnel/connectors/cdc/base/utils/SourceRecordUtilsTest.java
@@ -17,6 +17,8 @@
package org.apache.seatunnel.connectors.cdc.base.utils;
+import org.apache.seatunnel.api.table.catalog.TablePath;
+
import org.apache.kafka.connect.data.Schema;
import org.apache.kafka.connect.data.SchemaBuilder;
import org.apache.kafka.connect.data.Struct;
@@ -25,7 +27,9 @@ import org.apache.kafka.connect.source.SourceRecord;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
+import io.debezium.connector.AbstractSourceInfo;
import io.debezium.data.Envelope;
+import io.debezium.relational.TableId;
import java.util.Collections;
@@ -293,4 +297,45 @@ public class SourceRecordUtilsTest {
SourceRecord record = buildRecord(valueSchema, value);
Assertions.assertNull(SourceRecordUtils.getGtid(record));
}
+
+ /**
+ * Vitess exposes the logical database as keyspace, so table identity must still resolve even
+ * when Debezium leaves database_name empty or blank.
+ */
+ @Test
+ public void testGetTablePathUsesKeyspaceWhenDatabaseNameIsMissing() {
+ assertVitessTableIdentity(null);
+ assertVitessTableIdentity("");
+ }
+
+ /**
+ * Builds a minimal Vitess-like source record and verifies both SeaTunnel and Debezium table
+ * identifiers fall back to keyspace when the generic database field is absent.
+ */
+ private static void assertVitessTableIdentity(String databaseName) {
+ Schema sourceSchema =
+ SchemaBuilder.struct()
+ .field(
+ AbstractSourceInfo.DATABASE_NAME_KEY,
+ SchemaBuilder.string().optional().build())
+ .field("keyspace", SchemaBuilder.string().build())
+ .field(AbstractSourceInfo.TABLE_NAME_KEY, SchemaBuilder.string().build())
+ .build();
+ Struct sourceStruct =
+ new Struct(sourceSchema)
+ .put(AbstractSourceInfo.DATABASE_NAME_KEY, databaseName)
+ .put("keyspace", "inventory")
+ .put(AbstractSourceInfo.TABLE_NAME_KEY, "products");
+ Schema valueSchema =
+ SchemaBuilder.struct().field(Envelope.FieldName.SOURCE, sourceSchema).build();
+ Struct valueStruct = new Struct(valueSchema).put(Envelope.FieldName.SOURCE, sourceStruct);
+ SourceRecord record =
+ new SourceRecord(null, null, "vitess", null, null, valueSchema, valueStruct);
+
+ TablePath tablePath = SourceRecordUtils.getTablePath(record);
+ TableId tableId = SourceRecordUtils.getTableId(record);
+
+ Assertions.assertEquals(TablePath.of("inventory", null, "products"), tablePath);
+ Assertions.assertEquals(new TableId("inventory", null, "products"), tableId);
+ }
}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/pom.xml b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/pom.xml
new file mode 100644
index 0000000000..29bf8763e5
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/pom.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-cdc</artifactId>
+ <version>${revision}</version>
+ </parent>
+
+ <artifactId>connector-cdc-vitess</artifactId>
+ <name>SeaTunnel : Connectors V2 : CDC : Vitess</name>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-cdc-base</artifactId>
+ <version>${project.version}</version>
+ <scope>compile</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-jdbc</artifactId>
+ <version>${project.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.debezium</groupId>
+ <artifactId>debezium-connector-vitess</artifactId>
+ <version>${debezium.version}</version>
+ <scope>compile</scope>
+ <exclusions>
+ <exclusion>
+ <groupId>io.debezium</groupId>
+ <artifactId>debezium-core</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>io.debezium</groupId>
+ <artifactId>debezium-api</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>org.testcontainers</groupId>
+ <artifactId>mysql</artifactId>
+ <version>${testcontainer.version}</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-cdc-base</artifactId>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-jdbc</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>io.debezium</groupId>
+ <artifactId>debezium-connector-vitess</artifactId>
+ </dependency>
+
+ <dependency>
+ <groupId>org.testcontainers</groupId>
+ <artifactId>mysql</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>mysql</groupId>
+ <artifactId>mysql-connector-java</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+</project>
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceConfig.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceConfig.java
new file mode 100644
index 0000000000..adc63890c2
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceConfig.java
@@ -0,0 +1,259 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config;
+
+import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.type.SeaTunnelRow;
+import org.apache.seatunnel.connectors.cdc.base.option.SourceOptions;
+import org.apache.seatunnel.connectors.cdc.base.option.StartupMode;
+import org.apache.seatunnel.connectors.cdc.debezium.DebeziumDeserializationSchema;
+import org.apache.seatunnel.connectors.cdc.debezium.DeserializeFormat;
+import org.apache.seatunnel.connectors.cdc.debezium.row.DebeziumJsonDeserializeSchema;
+import org.apache.seatunnel.connectors.cdc.debezium.row.SeaTunnelRowDebeziumDeserializeSchema;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessTableSchemaState;
+
+import io.debezium.connector.vitess.SourceInfo;
+import io.debezium.connector.vitess.Vgtid;
+
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/**
+ * Immutable runtime configuration for the Vitess CDC source.
+ *
+ * <p>The connector keeps startup semantics here instead of leaking Debezium-specific options into
+ * the source reader.
+ */
+public final class VitessSourceConfig {
+
+ /** Captured tables must stay deterministic so downstream table identity remains stable. */
+ private final List<CatalogTable> catalogTables;
+
+ /** SeaTunnel-owned connector options. */
+ private final ReadonlyConfig options;
+
+ /** Startup mode is limited on purpose for the first delivery. */
+ private final StartupMode startupMode;
+
+ /** Stable VGTID used when startup.mode=specific. */
+ private final String specificStartupVgtid;
+
+ private VitessSourceConfig(
+ ReadonlyConfig options,
+ List<CatalogTable> catalogTables,
+ StartupMode startupMode,
+ String specificStartupVgtid) {
+ this.options = options;
+ this.catalogTables = Collections.unmodifiableList(new ArrayList<>(catalogTables));
+ this.startupMode = startupMode;
+ this.specificStartupVgtid = specificStartupVgtid;
+ }
+
+ /**
+ * Builds the validated connector configuration.
+ *
+ * <p>Vitess does not expose database/schema names the same way as MySQL-based connectors, so
+ * table paths must already be deterministic before the source starts.
+ */
+ public static VitessSourceConfig of(ReadonlyConfig options, List<CatalogTable> catalogTables) {
+ if (catalogTables == null || catalogTables.isEmpty()) {
+ throw new IllegalArgumentException(
+ "Vitess CDC requires resolved catalog tables for deterministic table identity.");
+ }
+
+ String keyspace = options.get(VitessSourceOptions.KEYSPACE);
+ for (CatalogTable catalogTable : catalogTables) {
+ String databaseName = catalogTable.getTablePath().getDatabaseName();
+ if (databaseName == null) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC requires database-qualified table paths, but table '%s' does not define a database name.",
+ catalogTable.getTablePath()));
+ }
+ if (!keyspace.equals(databaseName)) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC captures one keyspace per source. Table '%s' does not belong to keyspace '%s'.",
+ catalogTable.getTablePath(), keyspace));
+ }
+ if (catalogTable.getTablePath().getSchemaName() != null) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC does not support schema-qualified table paths. Table '%s' contains an unexpected schema component.",
+ catalogTable.getTablePath()));
+ }
+ }
+
+ StartupMode startupMode = options.get(VitessSourceOptions.STARTUP_MODE);
+ String specificVgtid =
+ options.getOptional(VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID).orElse(null);
+ if (startupMode == StartupMode.SPECIFIC) {
+ if (specificVgtid == null) {
+ throw new IllegalArgumentException(
+ "startup.specific-offset.vgtid is required when startup.mode=specific.");
+ }
+ // Parse eagerly so configuration failures surface before the source thread starts.
+ Vgtid.of(specificVgtid);
+ }
+
+ return new VitessSourceConfig(options, catalogTables, startupMode, specificVgtid);
+ }
+
+ /** Returns the user-facing connector name used by plugin registration. */
+ public String getPluginName() {
+ return "Vitess-CDC";
+ }
+
+ /** Returns the resolved output tables. */
+ public List<CatalogTable> getCatalogTables() {
+ return catalogTables;
+ }
+
+ /** Creates the initial split so checkpoint state already contains the startup intent. */
+ public VitessSourceSplit createInitialSplit() {
+ return new VitessSourceSplit(
+ VitessSourceSplit.SPLIT_ID,
+ createStartupOffset(),
+ VitessTableSchemaState.serializeCatalogTables(catalogTables),
+ catalogTables);
+ }
+
+ /** Creates the Debezium deserializer selected by the SeaTunnel format option. */
+ @SuppressWarnings("unchecked")
+ public DebeziumDeserializationSchema<SeaTunnelRow> createDeserializer() {
+ if (DeserializeFormat.COMPATIBLE_DEBEZIUM_JSON.equals(options.get(SourceOptions.FORMAT))) {
+ return new DebeziumJsonDeserializeSchema(getDebeziumPropertiesAsMap());
+ }
+ return SeaTunnelRowDebeziumDeserializeSchema.builder()
+ .setTables(catalogTables)
+ .setServerTimeZone(ZoneId.of(options.get(VitessSourceOptions.SERVER_TIME_ZONE)))
+ .build();
+ }
+
+ /**
+ * Builds Debezium properties while keeping SeaTunnel-owned semantics authoritative.
+ *
+ * <p>Pass-through Debezium properties are applied first so connector-owned options can safely
+ * overwrite conflicting low-level keys.
+ */
+ public Properties toDebeziumProperties() {
+ Properties properties = new Properties();
+ properties.putAll(getDebeziumPropertiesAsMap());
+
+ String logicalName = buildLogicalName();
+ properties.setProperty("connector.class", "io.debezium.connector.vitess.VitessConnector");
+ properties.setProperty("name", logicalName);
+ properties.setProperty("tasks.max", "1");
+ properties.setProperty("database.server.name", logicalName);
+ properties.setProperty("database.hostname", options.get(VitessSourceOptions.HOSTNAME));
+ properties.setProperty(
+ "database.port", String.valueOf(options.get(VitessSourceOptions.PORT)));
+ properties.setProperty("vitess.keyspace", options.get(VitessSourceOptions.KEYSPACE));
+ properties.setProperty(
+ "vitess.tablet.type", options.get(VitessSourceOptions.TABLET_TYPE).name());
+ properties.setProperty(
+ "vitess.stop_on_reshard",
+ String.valueOf(options.get(VitessSourceOptions.STOP_ON_RESHARD)));
+ properties.setProperty(
+ "vitess.keepalive.interval.ms",
+ String.valueOf(options.get(VitessSourceOptions.KEEPALIVE_INTERVAL_MS)));
+ properties.setProperty(
+ "vitess.grpc.max_inbound_message_size",
+ String.valueOf(options.get(VitessSourceOptions.GRPC_MAX_INBOUND_MESSAGE_SIZE)));
+ properties.setProperty("plugin.name", "decoderbufs");
+ properties.setProperty("include.schema.changes", "false");
+
+ options.getOptional(VitessSourceOptions.USERNAME)
+ .ifPresent(
+ username -> {
+ properties.setProperty("database.user", username);
+ properties.setProperty("vitess.database.user", username);
+ });
+ options.getOptional(VitessSourceOptions.PASSWORD)
+ .ifPresent(
+ password -> {
+ properties.setProperty("database.password", password);
+ properties.setProperty("vitess.database.password", password);
+ });
+ options.getOptional(VitessSourceOptions.SHARD)
+ .ifPresent(shard -> properties.setProperty("vitess.shard", shard));
+ options.getOptional(VitessSourceOptions.GRPC_HEADERS)
+ .ifPresent(headers -> properties.setProperty("vitess.grpc.headers", headers));
+
+ properties.setProperty(
+ "table.include.list",
+ catalogTables.stream()
+ .map(catalogTable -> catalogTable.getTablePath().toString())
+ .collect(Collectors.joining(",")));
+
+ // LATEST intentionally uses Vitess' symbolic current position for convenience startup.
+ // SPECIFIC uses an explicit VGTID and is the reproducible startup path.
+ if (startupMode == StartupMode.SPECIFIC) {
+ properties.setProperty("vitess.gtid", specificStartupVgtid);
+ } else {
+ properties.setProperty("vitess.gtid", "current");
+ }
+
+ return properties;
+ }
+
+ /** Returns the initial offset stored in the split before the first CDC row is emitted. */
+ public Map<String, Object> createStartupOffset() {
+ if (startupMode != StartupMode.SPECIFIC) {
+ return null;
+ }
+ Map<String, Object> offset = new HashMap<>();
+ offset.put(SourceInfo.VGTID_KEY, specificStartupVgtid);
+ return offset;
+ }
+
+ private Map<String, String> getDebeziumPropertiesAsMap() {
+ return options.getOptional(SourceOptions.DEBEZIUM_PROPERTIES)
+ .orElse(Collections.emptyMap());
+ }
+
+ private String buildLogicalName() {
+ String keyspace = options.get(VitessSourceOptions.KEYSPACE);
+ String sanitized = Pattern.compile("[^A-Za-z0-9_]").matcher(keyspace).replaceAll("_");
+ return "seatunnel_vitess_" + sanitized;
+ }
+
+ @Override
+ public String toString() {
+ return "VitessSourceConfig{"
+ + "catalogTables="
+ + catalogTables.stream()
+ .map(catalogTable -> catalogTable.getTablePath().toString())
+ .collect(Collectors.toList())
+ + ", startupMode="
+ + startupMode
+ + ", specificStartupVgtid='"
+ + specificStartupVgtid
+ + '\''
+ + '}';
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceOptions.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceOptions.java
new file mode 100644
index 0000000000..e8f8fb5f97
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceOptions.java
@@ -0,0 +1,144 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config;
+
+import org.apache.seatunnel.api.configuration.Option;
+import org.apache.seatunnel.api.configuration.Options;
+import org.apache.seatunnel.connectors.cdc.base.option.SourceOptions;
+import org.apache.seatunnel.connectors.cdc.base.option.StartupMode;
+
+import io.debezium.connector.vitess.connection.VitessTabletType;
+
+import java.util.Arrays;
+
+/** Source options owned by the Vitess CDC connector. */
+public final class VitessSourceOptions {
+
+ /** VTGate hostname used by the VStream gRPC client. */
+ public static final Option<String> HOSTNAME =
+ Options.key("hostname")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Hostname or IP address of the Vitess VTGate gRPC server.");
+
+ /** VTGate VStream gRPC port. */
+ public static final Option<Integer> PORT =
+ Options.key("port")
+ .intType()
+ .defaultValue(15991)
+ .withDescription("Port of the Vitess VTGate gRPC server.");
+
+ /** Optional VTGate username when the cluster enables authentication. */
+ public static final Option<String> USERNAME =
+ Options.key("username")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Username used by the Vitess VTGate gRPC connection.");
+
+ /** Optional VTGate password when the cluster enables authentication. */
+ public static final Option<String> PASSWORD =
+ Options.key("password")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Password used by the Vitess VTGate gRPC connection.");
+
+ /** Single keyspace captured by one connector instance. */
+ public static final Option<String> KEYSPACE =
+ Options.key("keyspace")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Vitess keyspace to capture.");
+
+ /**
+ * Optional shard restriction for deployments that intentionally bind one connector to one
+ * shard.
+ */
+ public static final Option<String> SHARD =
+ Options.key("shard")
+ .stringType()
+ .noDefaultValue()
+ .withDescription(
+ "Optional shard restriction. When omitted, the connector captures all shards in the configured keyspace.");
+
+ /**
+ * Startup mode is intentionally narrow so the first delivery keeps startup semantics explicit.
+ */
+ public static final Option<StartupMode> STARTUP_MODE =
+ Options.key(SourceOptions.STARTUP_MODE_KEY)
+ .singleChoice(
+ StartupMode.class,
+ Arrays.asList(StartupMode.LATEST, StartupMode.SPECIFIC))
+ .defaultValue(StartupMode.LATEST)
+ .withDescription(
+ "Startup mode for Vitess CDC. Supported values are "
+ + "\"latest\" and \"specific\". "
+ + "\"specific\" is the stable startup path for reproducible restore semantics.");
+
+ /** Stable startup VGTID used when startup.mode=specific. */
+ public static final Option<String> STARTUP_SPECIFIC_OFFSET_VGTID =
+ Options.key("startup.specific-offset.vgtid")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Vitess VGTID used when startup.mode is set to specific.");
+
+ /** The tablet type used by Vitess streaming. */
+ public static final Option<VitessTabletType> TABLET_TYPE =
+ Options.key("tablet-type")
+ .enumType(VitessTabletType.class)
+ .defaultValue(VitessTabletType.MASTER)
+ .withDescription(
+ "Vitess tablet type used by VStream. Supported values are MASTER, REPLICA and RDONLY.");
+
+ /** Whether VStream should stop after resharding. */
+ public static final Option<Boolean> STOP_ON_RESHARD =
+ Options.key("stop-on-reshard")
+ .booleanType()
+ .defaultValue(false)
+ .withDescription("Whether the connector should stop after Vitess resharding.");
+
+ /** Optional gRPC keepalive interval. */
+ public static final Option<Long> KEEPALIVE_INTERVAL_MS =
+ Options.key("keepalive.interval.ms")
+ .longType()
+ .defaultValue(Long.MAX_VALUE)
+ .withDescription(
+ "VStream gRPC keepalive interval in milliseconds. Long.MAX_VALUE disables keepalive.");
+
+ /** Optional raw gRPC headers passed through to VTGate. */
+ public static final Option<String> GRPC_HEADERS =
+ Options.key("grpc.headers")
+ .stringType()
+ .noDefaultValue()
+ .withDescription("Optional comma-separated gRPC headers in key:value format.");
+
+ /** Maximum inbound gRPC message size. */
+ public static final Option<Integer> GRPC_MAX_INBOUND_MESSAGE_SIZE =
+ Options.key("grpc.max-inbound-message-size")
+ .intType()
+ .defaultValue(4_194_304)
+ .withDescription("Maximum inbound VStream gRPC message size in bytes.");
+
+ /** Time zone used by SeaTunnel row deserialization for temporal normalization. */
+ public static final Option<String> SERVER_TIME_ZONE =
+ Options.key("server-time-zone")
+ .stringType()
+ .defaultValue("UTC")
+ .withDescription("Time zone used by SeaTunnel row deserialization.");
+
+ private VitessSourceOptions() {}
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSource.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSource.java
new file mode 100644
index 0000000000..f8902148c6
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSource.java
@@ -0,0 +1,84 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source;
+
+import org.apache.seatunnel.api.source.Boundedness;
+import org.apache.seatunnel.api.source.SeaTunnelSource;
+import org.apache.seatunnel.api.source.SourceReader;
+import org.apache.seatunnel.api.source.SourceSplitEnumerator;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.type.SeaTunnelRow;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceConfig;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.enumerator.VitessSourceEnumerator;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.enumerator.VitessSourceEnumeratorState;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.reader.VitessSourceReader;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import java.util.Collections;
+import java.util.List;
+
+/** SeaTunnel source implementation for Vitess CDC. */
+public class VitessSource
+ implements SeaTunnelSource<SeaTunnelRow, VitessSourceSplit, VitessSourceEnumeratorState> {
+
+ public static final String IDENTIFIER = "Vitess-CDC";
+
+ /** Immutable connector configuration used by reader and enumerator. */
+ private final VitessSourceConfig sourceConfig;
+
+ public VitessSource(VitessSourceConfig sourceConfig) {
+ this.sourceConfig = sourceConfig;
+ }
+
+ @Override
+ public Boundedness getBoundedness() {
+ return Boundedness.UNBOUNDED;
+ }
+
+ @Override
+ public String getPluginName() {
+ return IDENTIFIER;
+ }
+
+ @Override
+ public List<CatalogTable> getProducedCatalogTables() {
+ return sourceConfig.getCatalogTables();
+ }
+
+ @Override
+ public SourceReader<SeaTunnelRow, VitessSourceSplit> createReader(
+ SourceReader.Context readerContext) {
+ return new VitessSourceReader(readerContext, sourceConfig);
+ }
+
+ @Override
+ public SourceSplitEnumerator<VitessSourceSplit, VitessSourceEnumeratorState> createEnumerator(
+ SourceSplitEnumerator.Context<VitessSourceSplit> enumeratorContext) {
+ return new VitessSourceEnumerator(
+ enumeratorContext,
+ new VitessSourceEnumeratorState(
+ Collections.singletonList(sourceConfig.createInitialSplit())));
+ }
+
+ @Override
+ public SourceSplitEnumerator<VitessSourceSplit, VitessSourceEnumeratorState> restoreEnumerator(
+ SourceSplitEnumerator.Context<VitessSourceSplit> enumeratorContext,
+ VitessSourceEnumeratorState checkpointState) {
+ return new VitessSourceEnumerator(enumeratorContext, checkpointState);
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java
new file mode 100644
index 0000000000..3528cfb814
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java
@@ -0,0 +1,252 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source;
+
+import org.apache.seatunnel.api.configuration.util.OptionRule;
+import org.apache.seatunnel.api.options.ConnectorCommonOptions;
+import org.apache.seatunnel.api.options.table.ColumnOptions;
+import org.apache.seatunnel.api.source.SeaTunnelSource;
+import org.apache.seatunnel.api.source.SourceSplit;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.connector.TableSource;
+import org.apache.seatunnel.api.table.factory.ChangeStreamTableSourceFactory;
+import org.apache.seatunnel.api.table.factory.ChangeStreamTableSourceState;
+import org.apache.seatunnel.api.table.factory.Factory;
+import org.apache.seatunnel.api.table.factory.TableSourceFactoryContext;
+import org.apache.seatunnel.connectors.cdc.base.option.SourceOptions;
+import org.apache.seatunnel.connectors.cdc.base.option.StartupMode;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceConfig;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceOptions;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import com.google.auto.service.AutoService;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/** Factory for the Vitess CDC source connector. */
+@AutoService(Factory.class)
+public class VitessSourceFactory implements ChangeStreamTableSourceFactory {
+
+ @Override
+ public String factoryIdentifier() {
+ return VitessSource.IDENTIFIER;
+ }
+
+ @Override
+ public OptionRule optionRule() {
+ return OptionRule.builder()
+ .required(VitessSourceOptions.HOSTNAME, VitessSourceOptions.KEYSPACE)
+ .exclusive(ConnectorCommonOptions.SCHEMA, ConnectorCommonOptions.TABLE_CONFIGS)
+ .optional(
+ ConnectorCommonOptions.TABLE_NAMES,
+ ConnectorCommonOptions.TABLE_PATTERN,
+ ConnectorCommonOptions.METALAKE_TYPE,
+ VitessSourceOptions.PORT,
+ VitessSourceOptions.USERNAME,
+ VitessSourceOptions.PASSWORD,
+ VitessSourceOptions.SHARD,
+ VitessSourceOptions.STARTUP_MODE,
+ VitessSourceOptions.TABLET_TYPE,
+ VitessSourceOptions.STOP_ON_RESHARD,
+ VitessSourceOptions.KEEPALIVE_INTERVAL_MS,
+ VitessSourceOptions.GRPC_HEADERS,
+ VitessSourceOptions.GRPC_MAX_INBOUND_MESSAGE_SIZE,
+ VitessSourceOptions.SERVER_TIME_ZONE,
+ SourceOptions.FORMAT,
+ SourceOptions.DEBEZIUM_PROPERTIES)
+ .conditional(
+ VitessSourceOptions.STARTUP_MODE,
+ StartupMode.SPECIFIC,
+ VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID)
+ .build();
+ }
+
+ @Override
+ public Class<? extends SeaTunnelSource> getSourceClass() {
+ return VitessSource.class;
+ }
+
+ @Override
+ public <T, SplitT extends SourceSplit, StateT extends Serializable>
+ TableSource<T, SplitT, StateT> createSource(TableSourceFactoryContext context) {
+ return createVitessTableSource(context, Collections.emptyList());
+ }
+
+ @Override
+ public <T, SplitT extends SourceSplit, StateT extends Serializable>
+ TableSource<T, SplitT, StateT> restoreSource(
+ TableSourceFactoryContext context,
+ ChangeStreamTableSourceState<StateT, SplitT> state) {
+ return createVitessTableSource(context, extractCheckpointTables(state));
+ }
+
+ @SuppressWarnings("unchecked")
+ private <T, SplitT extends SourceSplit, StateT extends Serializable>
+ TableSource<T, SplitT, StateT> createVitessTableSource(
+ TableSourceFactoryContext context, List<CatalogTable> checkpointTables) {
+ return () -> {
+ List<CatalogTable> catalogTables =
+ checkpointTables.isEmpty() ? resolveCatalogTables(context) : checkpointTables;
+ VitessSourceConfig sourceConfig =
+ VitessSourceConfig.of(context.getOptions(), catalogTables);
+ return (SeaTunnelSource<T, SplitT, StateT>) new VitessSource(sourceConfig);
+ };
+ }
+
+ /**
+ * Vitess does not provide a SeaTunnel catalog implementation yet, so the first delivery keeps
+ * schema discovery deterministic by requiring explicit schema metadata from the user.
+ */
+ private List<CatalogTable> resolveCatalogTables(TableSourceFactoryContext context) {
+ validateSchemaMetadataContract(context);
+ validateSelectionOptions(context);
+ return filterDeclaredTables(context, discoverTableSchemas(context));
+ }
+
+ private void validateSchemaMetadataContract(TableSourceFactoryContext context) {
+ Optional<Map<String, Object>> singleSchema =
+ context.getOptions().getOptional(ConnectorCommonOptions.SCHEMA);
+ Optional<List<Map<String, Object>>> tableConfigs =
+ context.getOptions().getOptional(ConnectorCommonOptions.TABLE_CONFIGS);
+ if (singleSchema.isPresent()) {
+ validateRootSchemaDefinition(singleSchema.get(), "schema");
+ return;
+ }
+ if (tableConfigs.isPresent()) {
+ List<Map<String, Object>> configs = tableConfigs.get();
+ if (configs.isEmpty()) {
+ throw new IllegalArgumentException("tables_configs can not be empty.");
+ }
+ for (int index = 0; index < configs.size(); index++) {
+ validateSchemaDefinition(configs.get(index), "tables_configs[" + index + "]");
+ }
+ return;
+ }
+ throw new IllegalArgumentException(
+ "Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'.");
+ }
+
+ @SuppressWarnings("unchecked")
+ private void validateRootSchemaDefinition(Map<String, Object> schema, String optionName) {
+ if (!schema.containsKey(ColumnOptions.COLUMNS.key())
+ && !schema.containsKey(ColumnOptions.METADATA_TABLE_ID.key())) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC requires explicit columns or metadata_table_id in '%s' so table schemas stay deterministic.",
+ optionName));
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private void validateSchemaDefinition(Map<String, Object> config, String optionName) {
+ Object schemaValue = config.get(ConnectorCommonOptions.SCHEMA.key());
+ if (!(schemaValue instanceof Map)) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC requires explicit schema metadata. '%s' must contain a schema block.",
+ optionName));
+ }
+ validateRootSchemaDefinition((Map<String, Object>) schemaValue, optionName + ".schema");
+ }
+
+ private void validateSelectionOptions(TableSourceFactoryContext context) {
+ if (context.getOptions().getOptional(ConnectorCommonOptions.TABLE_NAMES).isPresent()
+ && context.getOptions()
+ .getOptional(ConnectorCommonOptions.TABLE_PATTERN)
+ .isPresent()) {
+ throw new IllegalArgumentException(
+ "Vitess CDC accepts either table-names or table-pattern, but not both.");
+ }
+ }
+
+ private List<CatalogTable> filterDeclaredTables(
+ TableSourceFactoryContext context, List<CatalogTable> declaredTables) {
+ Optional<List<String>> explicitTableNames =
+ context.getOptions().getOptional(ConnectorCommonOptions.TABLE_NAMES);
+ if (explicitTableNames.isPresent()) {
+ List<CatalogTable> selectedTables = new ArrayList<>(explicitTableNames.get().size());
+ for (String tableName : explicitTableNames.get()) {
+ CatalogTable matchedTable =
+ declaredTables.stream()
+ .filter(table -> table.getTablePath().toString().equals(tableName))
+ .findFirst()
+ .orElseThrow(
+ () ->
+ new IllegalArgumentException(
+ String.format(
+ "Vitess CDC did not find schema metadata for declared table '%s'. Add it to schema/tables_configs first.",
+ tableName)));
+ selectedTables.add(matchedTable);
+ }
+ return selectedTables;
+ }
+
+ Optional<String> tablePattern =
+ context.getOptions().getOptional(ConnectorCommonOptions.TABLE_PATTERN);
+ if (tablePattern.isPresent()) {
+ Pattern regex = Pattern.compile(tablePattern.get());
+ List<CatalogTable> selectedTables =
+ declaredTables.stream()
+ .filter(
+ table ->
+ regex.matcher(table.getTablePath().toString())
+ .matches())
+ .collect(Collectors.toList());
+ if (selectedTables.isEmpty()) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC table-pattern '%s' did not match any declared schema table.",
+ tablePattern.get()));
+ }
+ return selectedTables;
+ }
+
+ return declaredTables;
+ }
+
+ private <SplitT extends SourceSplit, StateT extends Serializable>
+ List<CatalogTable> extractCheckpointTables(
+ ChangeStreamTableSourceState<StateT, SplitT> state) {
+ if (state == null || state.getSplits() == null) {
+ return Collections.emptyList();
+ }
+ for (List<SplitT> splitGroup : state.getSplits()) {
+ if (splitGroup == null) {
+ continue;
+ }
+ for (SplitT split : splitGroup) {
+ if (!(split instanceof VitessSourceSplit)) {
+ continue;
+ }
+ List<CatalogTable> checkpointTables =
+ ((VitessSourceSplit) split).getCheckpointTables();
+ if (checkpointTables != null && !checkpointTables.isEmpty()) {
+ return checkpointTables;
+ }
+ }
+ }
+ return Collections.emptyList();
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumerator.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumerator.java
new file mode 100644
index 0000000000..9f50e728c3
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumerator.java
@@ -0,0 +1,119 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.enumerator;
+
+import org.apache.seatunnel.api.source.SourceSplitEnumerator;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.OptionalInt;
+import java.util.Set;
+
+/**
+ * Enumerator for the first Vitess CDC delivery.
+ *
+ * <p>The connector intentionally owns one long-running streaming split. This keeps the first
+ * delivery narrow while still integrating with SeaTunnel checkpoint and restore semantics.
+ */
+public class VitessSourceEnumerator
+ implements SourceSplitEnumerator<VitessSourceSplit, VitessSourceEnumeratorState> {
+
+ /** Pending split list doubles as the checkpoint state. */
+ private final List<VitessSourceSplit> pendingSplits;
+
+ private final Context<VitessSourceSplit> context;
+
+ public VitessSourceEnumerator(
+ Context<VitessSourceSplit> context, VitessSourceEnumeratorState restoredState) {
+ this.context = context;
+ if (restoredState == null) {
+ this.pendingSplits = new ArrayList<>();
+ } else {
+ this.pendingSplits = restoredState.getPendingSplits();
+ }
+ }
+
+ @Override
+ public void open() {}
+
+ @Override
+ public void run() {
+ assignPendingSplits(context.registeredReaders());
+ }
+
+ @Override
+ public void close() throws IOException {}
+
+ @Override
+ public void addSplitsBack(List<VitessSourceSplit> splits, int subtaskId) {
+ if (splits == null || splits.isEmpty()) {
+ return;
+ }
+ pendingSplits.addAll(copySplits(splits));
+ assignPendingSplits(Collections.singleton(subtaskId));
+ }
+
+ @Override
+ public int currentUnassignedSplitSize() {
+ return pendingSplits.size();
+ }
+
+ @Override
+ public void handleSplitRequest(int subtaskId) {
+ assignPendingSplits(Collections.singleton(subtaskId));
+ }
+
+ @Override
+ public void registerReader(int subtaskId) {
+ assignPendingSplits(Collections.singleton(subtaskId));
+ }
+
+ @Override
+ public VitessSourceEnumeratorState snapshotState(long checkpointId) {
+ return new VitessSourceEnumeratorState(pendingSplits);
+ }
+
+ @Override
+ public void notifyCheckpointComplete(long checkpointId) {}
+
+ private void assignPendingSplits(Set<Integer> readers) {
+ if (pendingSplits.isEmpty() || readers == null || readers.isEmpty()) {
+ return;
+ }
+ OptionalInt readerId = readers.stream().mapToInt(Integer::intValue).min();
+ if (!readerId.isPresent()) {
+ return;
+ }
+ VitessSourceSplit split = pendingSplits.remove(0);
+ context.assignSplit(readerId.getAsInt(), split);
+ for (Integer registeredReader : readers) {
+ context.signalNoMoreSplits(registeredReader);
+ }
+ }
+
+ private static List<VitessSourceSplit> copySplits(List<VitessSourceSplit> splits) {
+ List<VitessSourceSplit> copies = new ArrayList<>(splits.size());
+ for (VitessSourceSplit split : splits) {
+ copies.add(split.copy());
+ }
+ return copies;
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumeratorState.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumeratorState.java
new file mode 100644
index 0000000000..b88db4cbb8
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/enumerator/VitessSourceEnumeratorState.java
@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.enumerator;
+
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/** Checkpoint state for the single-split Vitess enumerator. */
+public class VitessSourceEnumeratorState implements Serializable {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Pending splits are enough because the first delivery intentionally owns one streaming split.
+ */
+ private final List<VitessSourceSplit> pendingSplits;
+
+ public VitessSourceEnumeratorState(List<VitessSourceSplit> pendingSplits) {
+ List<VitessSourceSplit> copies = new ArrayList<>();
+ if (pendingSplits != null) {
+ for (VitessSourceSplit pendingSplit : pendingSplits) {
+ copies.add(pendingSplit.copy());
+ }
+ }
+ this.pendingSplits = Collections.unmodifiableList(copies);
+ }
+
+ public List<VitessSourceSplit> getPendingSplits() {
+ List<VitessSourceSplit> copies = new ArrayList<>(pendingSplits.size());
+ for (VitessSourceSplit pendingSplit : pendingSplits) {
+ copies.add(pendingSplit.copy());
+ }
+ return copies;
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessSourceReader.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessSourceReader.java
new file mode 100644
index 0000000000..7a16db3532
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessSourceReader.java
@@ -0,0 +1,379 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.reader;
+
+import org.apache.seatunnel.api.source.Collector;
+import org.apache.seatunnel.api.source.SourceReader;
+import org.apache.seatunnel.api.table.type.SeaTunnelRow;
+import org.apache.seatunnel.connectors.cdc.debezium.DebeziumDeserializationSchema;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceConfig;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessTableSchemaState;
+
+import org.apache.kafka.connect.source.SourceRecord;
+
+import io.debezium.config.Configuration;
+import io.debezium.connector.base.ChangeEventQueue;
+import io.debezium.connector.vitess.Filters;
+import io.debezium.connector.vitess.VitessChangeEventSourceFactory;
+import io.debezium.connector.vitess.VitessConnectorConfig;
+import io.debezium.connector.vitess.VitessDatabaseSchema;
+import io.debezium.connector.vitess.VitessErrorHandler;
+import io.debezium.connector.vitess.VitessEventMetadataProvider;
+import io.debezium.connector.vitess.VitessOffsetContext;
+import io.debezium.connector.vitess.VitessPartition;
+import io.debezium.connector.vitess.VitessTaskContext;
+import io.debezium.connector.vitess.VitessTopicSelector;
+import io.debezium.connector.vitess.connection.VitessReplicationConnection;
+import io.debezium.pipeline.ChangeEventSourceCoordinator;
+import io.debezium.pipeline.DataChangeEvent;
+import io.debezium.pipeline.EventDispatcher;
+import io.debezium.pipeline.metrics.DefaultChangeEventSourceMetricsFactory;
+import io.debezium.pipeline.spi.Offsets;
+import io.debezium.relational.Table;
+import io.debezium.relational.TableId;
+import io.debezium.relational.Tables;
+import io.debezium.schema.TopicSelector;
+import io.debezium.util.Clock;
+import io.debezium.util.LoggingContext;
+import io.debezium.util.SchemaNameAdjuster;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+import java.util.stream.Collectors;
+
+/**
+ * Source reader backed by Debezium Vitess streaming.
+ *
+ * <p>The reader owns one Debezium streaming runtime and persists the latest source offset directly
+ * in the SeaTunnel split so checkpoint / restore can resume from the last emitted Vitess position.
+ */
+public class VitessSourceReader implements SourceReader<SeaTunnelRow, VitessSourceSplit> {
+
+ /** Reader context is also used to request the single split. */
+ private final Context context;
+
+ /** Immutable connector configuration shared by runtime and checkpoint code. */
+ private final VitessSourceConfig sourceConfig;
+
+ /**
+ * Debezium deserializer is owned by the source config so startup semantics stay centralized.
+ */
+ private final DebeziumDeserializationSchema<SeaTunnelRow> deserializer;
+
+ /** Reader state is tiny but still guarded because snapshotState can race with pollNext. */
+ private final Object stateLock = new Object();
+
+ private final List<VitessSourceSplit> sourceSplits = new ArrayList<>(1);
+
+ private VitessStreamingRuntime runtime;
+
+ public VitessSourceReader(Context context, VitessSourceConfig sourceConfig) {
+ this.context = context;
+ this.sourceConfig = sourceConfig;
+ this.deserializer = sourceConfig.createDeserializer();
+ }
+
+ @Override
+ public void open() {
+ context.sendSplitRequest();
+ }
+
+ /**
+ * Polls Debezium records and updates the split offset inside the same critical section that
+ * emits SeaTunnel rows.
+ *
+ * <p>This keeps checkpoint state aligned with the last fully emitted source record.
+ */
+ @Override
+ public void pollNext(Collector<SeaTunnelRow> output) throws Exception {
+ VitessStreamingRuntime currentRuntime = ensureRuntime();
+ if (currentRuntime == null) {
+ return;
+ }
+
+ List<SourceRecord> records = currentRuntime.poll();
+ if (records.isEmpty()) {
+ return;
+ }
+
+ synchronized (output.getCheckpointLock()) {
+ synchronized (stateLock) {
+ VitessSourceSplit split = sourceSplits.get(0);
+ for (SourceRecord record : records) {
+ deserializer.deserialize(record, output);
+ split.setOffset(record.sourceOffset());
+ }
+ }
+ }
+ }
+
+ @Override
+ public List<VitessSourceSplit> snapshotState(long checkpointId) {
+ synchronized (stateLock) {
+ if (runtime != null && !sourceSplits.isEmpty()) {
+ Map<String, byte[]> runtimeTableSchemas = runtime.snapshotTableSchemas();
+ if (runtimeTableSchemas != null && !runtimeTableSchemas.isEmpty()) {
+ sourceSplits.get(0).setTableSchemas(runtimeTableSchemas);
+ }
+ }
+ return sourceSplits.stream().map(VitessSourceSplit::copy).collect(Collectors.toList());
+ }
+ }
+
+ @Override
+ public void addSplits(List<VitessSourceSplit> splits) {
+ synchronized (stateLock) {
+ if (!sourceSplits.isEmpty() && splits != null && !splits.isEmpty()) {
+ throw new IllegalStateException(
+ "Vitess CDC reader only supports one active streaming split.");
+ }
+ if (splits != null) {
+ for (VitessSourceSplit split : splits) {
+ sourceSplits.add(split.copy());
+ }
+ }
+ if (runtime == null && !sourceSplits.isEmpty()) {
+ // Start Debezium as soon as the split arrives so latest startup does not miss
+ // changes produced before the framework issues the first pollNext call.
+ runtime = new VitessStreamingRuntime(sourceConfig, sourceSplits.get(0));
+ }
+ }
+ }
+
+ @Override
+ public void handleNoMoreSplits() {}
+
+ @Override
+ public void notifyCheckpointComplete(long checkpointId) {}
+
+ @Override
+ public void close() throws IOException {
+ VitessStreamingRuntime currentRuntime;
+ synchronized (stateLock) {
+ currentRuntime = runtime;
+ runtime = null;
+ }
+ if (currentRuntime != null) {
+ currentRuntime.close();
+ }
+ }
+
+ private VitessStreamingRuntime ensureRuntime() {
+ synchronized (stateLock) {
+ if (sourceSplits.isEmpty()) {
+ return null;
+ }
+ if (runtime == null) {
+ runtime = new VitessStreamingRuntime(sourceConfig, sourceSplits.get(0));
+ }
+ return runtime;
+ }
+ }
+
+ /** Small Debezium runtime wrapper so the SeaTunnel reader can stay checkpoint-focused. */
+ static final class VitessStreamingRuntime implements AutoCloseable {
+
+ private final ChangeEventQueue<DataChangeEvent> queue;
+ private final VitessDatabaseSchema schema;
+ private final EventDispatcher<VitessPartition, TableId> dispatcher;
+ private final VitessReplicationConnection replicationConnection;
+ private final ChangeEventSourceCoordinator<VitessPartition, VitessOffsetContext>
+ coordinator;
+
+ /**
+ * Creates and starts the Debezium runtime for one SeaTunnel split using the same
+ * coordinator lifecycle as Debezium's official Vitess connector task.
+ */
+ VitessStreamingRuntime(VitessSourceConfig sourceConfig, VitessSourceSplit split) {
+ Properties properties = sourceConfig.toDebeziumProperties();
+ Configuration configuration = Configuration.from(properties);
+ VitessConnectorConfig connectorConfig = new VitessConnectorConfig(configuration);
+ TopicSelector<TableId> topicSelector =
+ VitessTopicSelector.defaultSelector(connectorConfig);
+ SchemaNameAdjuster schemaNameAdjuster =
+ connectorConfig.schemaNameAdjustmentMode().createAdjuster();
+ this.schema =
+ new VitessDatabaseSchema(connectorConfig, schemaNameAdjuster, topicSelector);
+ restoreTableSchemas(split.getTableSchemas());
+ this.queue =
+ new ChangeEventQueue.Builder<DataChangeEvent>()
+ .pollInterval(connectorConfig.getPollInterval())
+ .maxBatchSize(connectorConfig.getMaxBatchSize())
+ .maxQueueSize(connectorConfig.getMaxQueueSize())
+ .loggingContextSupplier(
+ () ->
+ LoggingContext.forConnector(
+ connectorConfig.getConnectorName(),
+ connectorConfig.getLogicalName(),
+ "seatunnel-vitess-cdc-reader"))
+ .build();
+
+ VitessErrorHandler errorHandler = new VitessErrorHandler(connectorConfig, queue);
+ this.dispatcher =
+ new EventDispatcher<>(
+ connectorConfig,
+ topicSelector,
+ schema,
+ queue,
+ createTableFilter(connectorConfig),
+ DataChangeEvent::new,
+ new VitessEventMetadataProvider(),
+ schemaNameAdjuster);
+ this.replicationConnection = new VitessReplicationConnection(connectorConfig, schema);
+ VitessTaskContext taskContext = new VitessTaskContext(connectorConfig, schema);
+ VitessPartition partition = new VitessPartition(connectorConfig.getLogicalName());
+ VitessOffsetContext previousOffset =
+ split.getOffset() == null
+ ? null
+ : new VitessOffsetContext.Loader(connectorConfig)
+ .load(split.getOffset());
+ this.coordinator =
+ new ChangeEventSourceCoordinator<>(
+ Offsets.of(partition, previousOffset),
+ errorHandler,
+ io.debezium.connector.vitess.VitessConnector.class,
+ connectorConfig,
+ new VitessChangeEventSourceFactory(
+ connectorConfig,
+ errorHandler,
+ dispatcher,
+ Clock.system(),
+ schema,
+ replicationConnection),
+ new DefaultChangeEventSourceMetricsFactory<>(),
+ dispatcher,
+ schema);
+ this.coordinator.start(taskContext, queue, new VitessEventMetadataProvider());
+ }
+
+ /**
+ * Debezium already batches SourceRecords for us, so the reader only converts queue items.
+ */
+ List<SourceRecord> poll() throws InterruptedException {
+ return queue.poll().stream()
+ .map(DataChangeEvent::getRecord)
+ .collect(Collectors.toList());
+ }
+
+ /**
+ * Captures the current Debezium table definitions so restore can resume from backlog rows
+ * without waiting for VTGate to resend FIELD metadata.
+ */
+ Map<String, byte[]> snapshotTableSchemas() {
+ Map<String, byte[]> tableSchemas = new HashMap<>();
+ for (TableId tableId : schema.tableIds()) {
+ Table table = schema.tableFor(tableId);
+ if (table != null) {
+ tableSchemas.put(
+ tableId.toDoubleQuotedString(),
+ VitessTableSchemaState.serialize(table));
+ }
+ }
+ return tableSchemas.isEmpty() ? null : tableSchemas;
+ }
+
+ @Override
+ public void close() throws IOException {
+ IOException closeException = null;
+
+ try {
+ coordinator.stop();
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ IOException interruptedException =
+ new IOException(
+ "Interrupted while stopping Vitess change-event coordinator", e);
+ if (closeException == null) {
+ closeException = interruptedException;
+ } else {
+ closeException.addSuppressed(interruptedException);
+ }
+ }
+
+ try {
+ replicationConnection.close();
+ } catch (Exception e) {
+ IOException connectionException =
+ new IOException("Failed to close Vitess replication connection", e);
+ if (closeException == null) {
+ closeException = connectionException;
+ } else {
+ closeException.addSuppressed(connectionException);
+ }
+ }
+
+ try {
+ schema.close();
+ } catch (Exception e) {
+ IOException schemaException =
+ new IOException("Failed to close Vitess database schema", e);
+ if (closeException == null) {
+ closeException = schemaException;
+ } else {
+ closeException.addSuppressed(schemaException);
+ }
+ }
+
+ if (closeException != null) {
+ throw closeException;
+ }
+ }
+
+ /**
+ * Debezium 1.9's Vitess connector keeps the table filter in its dedicated Filters helper
+ * instead of wiring RelationalDatabaseConnectorConfig#getTableFilters().
+ */
+ private static Tables.TableFilter createTableFilter(VitessConnectorConfig connectorConfig) {
+ return new AccessibleVitessFilters(connectorConfig).exposeTableFilter();
+ }
+
+ private void restoreTableSchemas(Map<String, byte[]> tableSchemas) {
+ if (tableSchemas == null || tableSchemas.isEmpty()) {
+ return;
+ }
+ tableSchemas.values().forEach(this::restoreTableSchema);
+ }
+
+ private void restoreTableSchema(byte[] tableSchemaBytes) {
+ Table restoredTable = VitessTableSchemaState.deserialize(tableSchemaBytes);
+ if (restoredTable != null) {
+ schema.applySchemaChangesForTable(restoredTable);
+ }
+ }
+ }
+
+ /** Small bridge that exposes Debezium's protected Vitess table filter. */
+ static final class AccessibleVitessFilters extends Filters {
+
+ AccessibleVitessFilters(VitessConnectorConfig connectorConfig) {
+ super(connectorConfig);
+ }
+
+ /**
+ * Returns the Debezium-owned table filter so SeaTunnel stays aligned with upstream logic.
+ */
+ private Tables.TableFilter exposeTableFilter() {
+ return super.tableFilter();
+ }
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessSourceSplit.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessSourceSplit.java
new file mode 100644
index 0000000000..0eca8d54b4
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessSourceSplit.java
@@ -0,0 +1,159 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split;
+
+import org.apache.seatunnel.api.source.SourceSplit;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Single streaming split used by the Vitess connector.
+ *
+ * <p>The split persists both the last committed Debezium source offset and the latest Debezium
+ * table definitions needed to decode backlog rows after checkpoint restore.
+ */
+public class VitessSourceSplit implements SourceSplit {
+
+ public static final String SPLIT_ID = "vitess-stream-split";
+
+ private static final long serialVersionUID = 1L;
+
+ /** Stable split id because the connector currently owns one streaming split per source. */
+ private final String splitId;
+
+ /** Debezium source offset stored in SeaTunnel checkpoints. */
+ private Map<String, Object> offset;
+
+ /**
+ * Serialized Debezium table definitions captured from FIELD events.
+ *
+ * <p>Vitess does not guarantee that field metadata is replayed after every resume position, so
+ * restore must keep the latest known schema together with the VGTID.
+ */
+ private Map<String, byte[]> tableSchemas;
+
+ /**
+ * SeaTunnel-side table schemas used to rebuild row converters during checkpoint restore.
+ *
+ * <p>The first Vitess delivery keeps schema evolution out of scope, so this stays aligned with
+ * the declared table schemas and must survive restart unchanged.
+ */
+ private List<CatalogTable> checkpointTables;
+
+ public VitessSourceSplit(String splitId, Map<String, Object> offset) {
+ this(splitId, offset, null, null);
+ }
+
+ public VitessSourceSplit(
+ String splitId, Map<String, Object> offset, Map<String, byte[]> tableSchemas) {
+ this(splitId, offset, tableSchemas, null);
+ }
+
+ public VitessSourceSplit(
+ String splitId,
+ Map<String, Object> offset,
+ Map<String, byte[]> tableSchemas,
+ List<CatalogTable> checkpointTables) {
+ this.splitId = splitId;
+ this.offset = copyOffset(offset);
+ this.tableSchemas = copyTableSchemas(tableSchemas);
+ this.checkpointTables = copyCheckpointTables(checkpointTables);
+ }
+
+ @Override
+ public String splitId() {
+ return splitId;
+ }
+
+ /**
+ * Returns a defensive copy so checkpoint callers cannot mutate in-memory state accidentally.
+ */
+ public Map<String, Object> getOffset() {
+ return copyOffset(offset);
+ }
+
+ /** Updates the in-memory checkpoint position after a record has been emitted successfully. */
+ public void setOffset(Map<String, ?> offset) {
+ this.offset = copyOffset(offset);
+ }
+
+ /** Returns the latest serialized Debezium table schemas captured for this split. */
+ public Map<String, byte[]> getTableSchemas() {
+ return copyTableSchemas(tableSchemas);
+ }
+
+ /** Updates the schema snapshot so restore can decode rows before new FIELD events arrive. */
+ public void setTableSchemas(Map<String, byte[]> tableSchemas) {
+ this.tableSchemas = copyTableSchemas(tableSchemas);
+ }
+
+ /** Returns the SeaTunnel schema snapshot used to rebuild the deserializer on restore. */
+ public List<CatalogTable> getCheckpointTables() {
+ return copyCheckpointTables(checkpointTables);
+ }
+
+ /** Creates a deep-enough copy for checkpoint serialization. */
+ public VitessSourceSplit copy() {
+ return new VitessSourceSplit(splitId, offset, tableSchemas, checkpointTables);
+ }
+
+ @Override
+ public String toString() {
+ return "VitessSourceSplit{"
+ + "splitId='"
+ + splitId
+ + '\''
+ + ", offset="
+ + offset
+ + ", tableSchemas="
+ + (tableSchemas == null ? 0 : tableSchemas.size())
+ + ", checkpointTables="
+ + (checkpointTables == null ? 0 : checkpointTables.size())
+ + '}';
+ }
+
+ private static Map<String, Object> copyOffset(Map<String, ?> offset) {
+ if (offset == null || offset.isEmpty()) {
+ return null;
+ }
+ return new HashMap<>(offset);
+ }
+
+ private static Map<String, byte[]> copyTableSchemas(Map<String, byte[]> tableSchemas) {
+ if (tableSchemas == null || tableSchemas.isEmpty()) {
+ return null;
+ }
+ Map<String, byte[]> copiedSchemas = new HashMap<>(tableSchemas.size());
+ tableSchemas.forEach(
+ (tableId, schemaBytes) ->
+ copiedSchemas.put(
+ tableId, schemaBytes == null ? null : schemaBytes.clone()));
+ return copiedSchemas;
+ }
+
+ private static List<CatalogTable> copyCheckpointTables(List<CatalogTable> checkpointTables) {
+ if (checkpointTables == null || checkpointTables.isEmpty()) {
+ return null;
+ }
+ return new ArrayList<>(checkpointTables);
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessTableSchemaState.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessTableSchemaState.java
new file mode 100644
index 0000000000..f4b8626466
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/split/VitessTableSchemaState.java
@@ -0,0 +1,250 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split;
+
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.catalog.PrimaryKey;
+import org.apache.seatunnel.api.table.type.SqlType;
+import org.apache.seatunnel.connectors.cdc.debezium.ConnectTableChangeSerializer;
+
+import org.apache.kafka.connect.data.Struct;
+import org.apache.kafka.connect.json.JsonConverter;
+
+import io.debezium.relational.Table;
+import io.debezium.relational.TableId;
+import io.debezium.relational.history.TableChanges;
+
+import java.sql.Types;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * Helper for persisting Debezium table definitions in Vitess split state.
+ *
+ * <p>Vitess may resume from a VGTID without replaying FIELD metadata immediately, so the connector
+ * keeps a checkpoint-safe copy of the latest known Debezium table schema.
+ */
+public final class VitessTableSchemaState {
+
+ private static final String SERIALIZATION_TOPIC = "vitess-table-schema-state";
+
+ private static final ConnectTableChangeSerializer TABLE_CHANGE_SERIALIZER =
+ new ConnectTableChangeSerializer();
+
+ private static final JsonConverter JSON_CONVERTER = new JsonConverter();
+
+ static {
+ JSON_CONVERTER.configure(Collections.singletonMap("schemas.enable", true), false);
+ }
+
+ private VitessTableSchemaState() {}
+
+ /** Serializes a Debezium table definition into checkpoint-safe bytes. */
+ public static byte[] serialize(Table table) {
+ TableChanges tableChanges = new TableChanges().create(table);
+ Struct tableChangeStruct = TABLE_CHANGE_SERIALIZER.serialize(tableChanges).get(0);
+ return JSON_CONVERTER.fromConnectData(
+ SERIALIZATION_TOPIC, tableChangeStruct.schema(), tableChangeStruct);
+ }
+
+ /** Restores one Debezium table definition from checkpoint bytes. */
+ public static Table deserialize(byte[] tableSchemaBytes) {
+ if (tableSchemaBytes == null || tableSchemaBytes.length == 0) {
+ return null;
+ }
+ Struct tableChangeStruct =
+ (Struct)
+ JSON_CONVERTER.toConnectData(SERIALIZATION_TOPIC, tableSchemaBytes).value();
+ TableChanges tableChanges =
+ TABLE_CHANGE_SERIALIZER.deserialize(
+ Collections.singletonList(tableChangeStruct), false);
+ return tableChanges.iterator().next().getTable();
+ }
+
+ /**
+ * Builds the initial schema snapshot from user-declared catalog tables.
+ *
+ * <p>This bootstrap path keeps startup.mode=specific reproducible even before VTGate re-sends
+ * FIELD metadata for the captured tables.
+ */
+ public static Map<String, byte[]> serializeCatalogTables(List<CatalogTable> catalogTables) {
+ if (catalogTables == null || catalogTables.isEmpty()) {
+ return null;
+ }
+ Map<String, byte[]> tableSchemas = new HashMap<>(catalogTables.size());
+ for (CatalogTable catalogTable : catalogTables) {
+ Table table = fromCatalogTable(catalogTable);
+ tableSchemas.put(table.id().toDoubleQuotedString(), serialize(table));
+ }
+ return tableSchemas;
+ }
+
+ private static Table fromCatalogTable(CatalogTable catalogTable) {
+ TableId tableId =
+ new TableId(
+ null,
+ catalogTable.getTablePath().getDatabaseName(),
+ catalogTable.getTablePath().getTableName());
+ List<io.debezium.relational.Column> columns =
+ new java.util.ArrayList<>(catalogTable.getTableSchema().getColumns().size());
+ int position = 1;
+ for (org.apache.seatunnel.api.table.catalog.Column catalogColumn :
+ catalogTable.getTableSchema().getColumns()) {
+ if (!catalogColumn.isPhysical()) {
+ continue;
+ }
+ columns.add(toDebeziumColumn(catalogColumn, position++));
+ }
+
+ io.debezium.relational.TableEditor tableEditor = Table.editor().tableId(tableId);
+ tableEditor.setColumns(columns);
+ PrimaryKey primaryKey = catalogTable.getTableSchema().getPrimaryKey();
+ if (primaryKey != null) {
+ tableEditor.setPrimaryKeyNames(primaryKey.getColumnNames());
+ }
+ return tableEditor.create();
+ }
+
+ /**
+ * Converts a SeaTunnel catalog column into a Debezium relational column definition.
+ *
+ * <p>The bootstrap schema is only used until real FIELD metadata arrives, so generic SQL type
+ * mappings are sufficient when the catalog column does not provide a database-specific
+ * sourceType.
+ */
+ private static io.debezium.relational.Column toDebeziumColumn(
+ org.apache.seatunnel.api.table.catalog.Column catalogColumn, int position) {
+ io.debezium.relational.ColumnEditor columnEditor =
+ io.debezium.relational.Column.editor()
+ .name(catalogColumn.getName())
+ .jdbcType(resolveJdbcType(catalogColumn))
+ .position(position)
+ .optional(catalogColumn.isNullable())
+ .comment(catalogColumn.getComment());
+
+ String typeExpression = normalizeTypeExpression(catalogColumn.getSourceType());
+ String typeName =
+ typeExpression == null
+ ? defaultTypeName(catalogColumn.getDataType().getSqlType())
+ : baseTypeName(typeExpression);
+ if (typeExpression == null) {
+ columnEditor.type(typeName);
+ } else {
+ columnEditor.type(typeName, typeExpression);
+ }
+
+ if (catalogColumn.getColumnLength() != null) {
+ columnEditor.length(Math.toIntExact(catalogColumn.getColumnLength()));
+ }
+ if (catalogColumn.getScale() != null) {
+ columnEditor.scale(catalogColumn.getScale());
+ }
+ return columnEditor.create();
+ }
+
+ private static int resolveJdbcType(org.apache.seatunnel.api.table.catalog.Column column) {
+ switch (column.getDataType().getSqlType()) {
+ case STRING:
+ return Types.VARCHAR;
+ case BOOLEAN:
+ return Types.BOOLEAN;
+ case TINYINT:
+ return Types.TINYINT;
+ case SMALLINT:
+ return Types.SMALLINT;
+ case INT:
+ return Types.INTEGER;
+ case BIGINT:
+ return Types.BIGINT;
+ case FLOAT:
+ return Types.FLOAT;
+ case DOUBLE:
+ return Types.DOUBLE;
+ case DECIMAL:
+ return Types.DECIMAL;
+ case BYTES:
+ return Types.BINARY;
+ case DATE:
+ return Types.DATE;
+ case TIME:
+ return Types.TIME;
+ case TIMESTAMP:
+ case TIMESTAMP_TZ:
+ return Types.TIMESTAMP;
+ default:
+ throw new IllegalArgumentException(
+ String.format(
+ "Vitess CDC bootstrap schema does not support catalog SQL type '%s' for column '%s'.",
+ column.getDataType().getSqlType(), column.getName()));
+ }
+ }
+
+ private static String defaultTypeName(SqlType sqlType) {
+ switch (sqlType) {
+ case STRING:
+ return "VARCHAR";
+ case BOOLEAN:
+ return "BOOLEAN";
+ case TINYINT:
+ return "TINYINT";
+ case SMALLINT:
+ return "SMALLINT";
+ case INT:
+ return "INT";
+ case BIGINT:
+ return "BIGINT";
+ case FLOAT:
+ return "FLOAT";
+ case DOUBLE:
+ return "DOUBLE";
+ case DECIMAL:
+ return "DECIMAL";
+ case BYTES:
+ return "BLOB";
+ case DATE:
+ return "DATE";
+ case TIME:
+ return "TIME";
+ case TIMESTAMP:
+ case TIMESTAMP_TZ:
+ return "TIMESTAMP";
+ default:
+ throw new IllegalArgumentException(
+ "Unsupported Vitess catalog SQL type: " + sqlType);
+ }
+ }
+
+ private static String normalizeTypeExpression(String sourceType) {
+ if (sourceType == null) {
+ return null;
+ }
+ String trimmed = sourceType.trim();
+ return trimmed.isEmpty() ? null : trimmed.toUpperCase(Locale.ROOT);
+ }
+
+ private static String baseTypeName(String typeExpression) {
+ int parenthesisIndex = typeExpression.indexOf('(');
+ if (parenthesisIndex < 0) {
+ return typeExpression;
+ }
+ return typeExpression.substring(0, parenthesisIndex).trim();
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactoryTest.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactoryTest.java
new file mode 100644
index 0000000000..b1603127da
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactoryTest.java
@@ -0,0 +1,387 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source;
+
+import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.catalog.PhysicalColumn;
+import org.apache.seatunnel.api.table.catalog.PrimaryKey;
+import org.apache.seatunnel.api.table.catalog.TableIdentifier;
+import org.apache.seatunnel.api.table.catalog.TablePath;
+import org.apache.seatunnel.api.table.catalog.TableSchema;
+import org.apache.seatunnel.api.table.connector.TableSource;
+import org.apache.seatunnel.api.table.factory.ChangeStreamTableSourceState;
+import org.apache.seatunnel.api.table.factory.TableSourceFactoryContext;
+import org.apache.seatunnel.api.table.type.BasicType;
+import org.apache.seatunnel.connectors.cdc.base.option.StartupMode;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceConfig;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceOptions;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/** Covers factory-path validation, schema selection, and restore semantics for Vitess CDC. */
+class VitessSourceFactoryTest {
+
+ private final VitessSourceFactory factory = new VitessSourceFactory();
+
+ /** Specific startup must fail fast when the connector does not receive a reproducible VGTID. */
+ @Test
+ void testSpecificStartupRequiresVgtid() {
+ IllegalArgumentException exception =
+ Assertions.assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ VitessSourceConfig.of(
+ createConfig(
+ StartupMode.SPECIFIC,
+ null,
+ null,
+ singleTableConfigs("test.products")),
+ testTable()));
+
+ Assertions.assertTrue(
+ exception.getMessage().contains("startup.specific-offset.vgtid is required"));
+ }
+
+ /** Specific startup must persist both the offset and the checkpoint table schema snapshot. */
+ @Test
+ void testSpecificStartupPersistsInitialCheckpointState() {
+ String startupVgtid = "[{\"keyspace\":\"test\",\"shard\":\"-\",\"gtid\":\"MySQL56/1-10\"}]";
+ VitessSourceConfig sourceConfig =
+ VitessSourceConfig.of(
+ createConfig(
+ StartupMode.SPECIFIC,
+ startupVgtid,
+ null,
+ singleTableConfigs("test.products")),
+ testTable());
+
+ VitessSourceSplit split = sourceConfig.createInitialSplit();
+
+ Assertions.assertEquals(startupVgtid, split.getOffset().get("vgtid"));
+ Assertions.assertNotNull(split.getTableSchemas());
+ Assertions.assertNotNull(split.getCheckpointTables());
+ Assertions.assertEquals(1, split.getCheckpointTables().size());
+ }
+
+ /**
+ * The factory must reject configs that declare tables without deterministic schema metadata.
+ */
+ @Test
+ void testFactoryRequiresExplicitSchemaMetadata() {
+ Map<String, Object> options = baseOptions(StartupMode.LATEST, null);
+ options.put("table-names", Collections.singletonList("test.products"));
+
+ TableSourceFactoryContext context =
+ new TableSourceFactoryContext(
+ ReadonlyConfig.fromMap(options), getClass().getClassLoader());
+
+ IllegalArgumentException exception =
+ Assertions.assertThrows(
+ IllegalArgumentException.class,
+ () -> factory.createSource(context).createSource());
+
+ Assertions.assertTrue(exception.getMessage().contains("requires explicit schema metadata"));
+ }
+
+ /** The factory must create sources from declared table schemas instead of catalog discovery. */
+ @Test
+ void testFactoryCreatesSourceFromDeclaredTableConfigs() {
+ TableSourceFactoryContext context =
+ createContext(
+ StartupMode.LATEST,
+ null,
+ null,
+ multiTableConfigs("test.products", "test.customers"));
+
+ VitessSource source = createVitessSource(factory.createSource(context));
+
+ Assertions.assertEquals(2, source.getProducedCatalogTables().size());
+ Assertions.assertEquals(
+ Arrays.asList("test.products", "test.customers"),
+ Arrays.asList(
+ source.getProducedCatalogTables().get(0).getTablePath().toString(),
+ source.getProducedCatalogTables().get(1).getTablePath().toString()));
+ }
+
+ /**
+ * Root-level schema must work for the single-table path instead of requiring tables_configs.
+ */
+ @Test
+ void testFactoryCreatesSourceFromRootSchema() {
+ TableSourceFactoryContext context =
+ createContext(
+ StartupMode.LATEST,
+ Collections.singletonList("test.products"),
+ null,
+ singleTableConfigs("test.products"));
+
+ VitessSource source = createVitessSource(factory.createSource(context));
+
+ Assertions.assertEquals(1, source.getProducedCatalogTables().size());
+ Assertions.assertEquals(
+ "test.products",
+ source.getProducedCatalogTables().get(0).getTablePath().toString());
+ Assertions.assertEquals(
+ 3, source.getProducedCatalogTables().get(0).getTableSchema().getColumns().size());
+ }
+
+ /** table-pattern must filter the declared schema list deterministically before startup. */
+ @Test
+ void testFactoryFiltersDeclaredTablesByPattern() {
+ Map<String, Object> options = baseOptions(StartupMode.LATEST, null);
+ options.put("table-pattern", "test\\.prod.*");
+ options.put("tables_configs", multiTableConfigs("test.products", "test.customers"));
+
+ TableSourceFactoryContext context =
+ new TableSourceFactoryContext(
+ ReadonlyConfig.fromMap(options), getClass().getClassLoader());
+
+ VitessSource source = createVitessSource(factory.createSource(context));
+
+ Assertions.assertEquals(1, source.getProducedCatalogTables().size());
+ Assertions.assertEquals(
+ "test.products",
+ source.getProducedCatalogTables().get(0).getTablePath().toString());
+ }
+
+ /**
+ * Restore must reuse the checkpoint table snapshot so the SeaTunnel row converter stays aligned
+ * with the split state instead of silently downgrading to the latest config.
+ */
+ @Test
+ void testRestoreSourceUsesCheckpointTables() {
+ List<CatalogTable> checkpointTables =
+ Collections.singletonList(
+ createTable(
+ "test",
+ "products",
+ Arrays.asList(
+ physicalColumn("id", BasicType.INT_TYPE),
+ physicalColumn("name", BasicType.STRING_TYPE),
+ physicalColumn("description", BasicType.STRING_TYPE))));
+ VitessSourceSplit split =
+ VitessSourceConfig.of(
+ createConfig(
+ StartupMode.SPECIFIC,
+ "[{\"keyspace\":\"test\",\"shard\":\"-\",\"gtid\":\"MySQL56/1-10\"}]",
+ Collections.singletonList("test.products"),
+ singleTableConfigs("test.products")),
+ checkpointTables)
+ .createInitialSplit();
+ ChangeStreamTableSourceState<Serializable, VitessSourceSplit> state =
+ new ChangeStreamTableSourceState<>(
+ null, Collections.singletonList(Collections.singletonList(split)));
+
+ TableSourceFactoryContext context =
+ createContext(
+ StartupMode.LATEST,
+ Collections.singletonList("test.products"),
+ null,
+ singleTableConfigsWithoutDescription("test.products"));
+
+ VitessSource restoredSource = createVitessSource(factory.restoreSource(context, state));
+
+ Assertions.assertEquals(
+ 3,
+ restoredSource
+ .getProducedCatalogTables()
+ .get(0)
+ .getTableSchema()
+ .getColumns()
+ .size());
+ Assertions.assertEquals(
+ "description",
+ restoredSource
+ .getProducedCatalogTables()
+ .get(0)
+ .getTableSchema()
+ .getColumns()
+ .get(2)
+ .getName());
+ }
+
+ /**
+ * Table resolution must stay inside one configured keyspace so runtime table identity is
+ * stable.
+ */
+ @Test
+ void testConfiguredKeyspaceRejectsForeignTable() {
+ IllegalArgumentException exception =
+ Assertions.assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ VitessSourceConfig.of(
+ createConfig(
+ StartupMode.LATEST,
+ null,
+ Collections.singletonList("test.products"),
+ singleTableConfigs("test.products")),
+ foreignTable()));
+
+ Assertions.assertTrue(
+ exception.getMessage().contains("does not belong to keyspace 'test'"));
+ }
+
+ private VitessSource createVitessSource(TableSource<?, VitessSourceSplit, ?> tableSource) {
+ return (VitessSource) tableSource.createSource();
+ }
+
+ private TableSourceFactoryContext createContext(
+ StartupMode startupMode,
+ List<String> tableNames,
+ String tablePattern,
+ List<Map<String, Object>> tableConfigs) {
+ return new TableSourceFactoryContext(
+ createConfig(startupMode, null, tableNames, tableConfigs, tablePattern),
+ getClass().getClassLoader());
+ }
+
+ private ReadonlyConfig createConfig(
+ StartupMode startupMode,
+ String specificVgtid,
+ List<String> tableNames,
+ List<Map<String, Object>> tableConfigs) {
+ return createConfig(startupMode, specificVgtid, tableNames, tableConfigs, null);
+ }
+
+ private ReadonlyConfig createConfig(
+ StartupMode startupMode,
+ String specificVgtid,
+ List<String> tableNames,
+ List<Map<String, Object>> tableConfigs,
+ String tablePattern) {
+ Map<String, Object> options = baseOptions(startupMode, specificVgtid);
+ if (tableNames != null) {
+ options.put("table-names", tableNames);
+ }
+ if (tablePattern != null) {
+ options.put("table-pattern", tablePattern);
+ }
+ if (tableConfigs.size() == 1) {
+ options.put("schema", tableConfigs.get(0).get("schema"));
+ } else {
+ options.put("tables_configs", tableConfigs);
+ }
+ return ReadonlyConfig.fromMap(options);
+ }
+
+ private Map<String, Object> baseOptions(StartupMode startupMode, String specificVgtid) {
+ Map<String, Object> options = new HashMap<>();
+ options.put(VitessSourceOptions.HOSTNAME.key(), "127.0.0.1");
+ options.put(VitessSourceOptions.KEYSPACE.key(), "test");
+ options.put(VitessSourceOptions.STARTUP_MODE.key(), startupMode.name());
+ if (specificVgtid != null) {
+ options.put(VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID.key(), specificVgtid);
+ }
+ return options;
+ }
+
+ private List<Map<String, Object>> singleTableConfigs(String tableName) {
+ return Collections.singletonList(tableConfig(tableName, true));
+ }
+
+ private List<Map<String, Object>> singleTableConfigsWithoutDescription(String tableName) {
+ return Collections.singletonList(tableConfig(tableName, false));
+ }
+
+ private List<Map<String, Object>> multiTableConfigs(String... tableNames) {
+ List<Map<String, Object>> configs = new ArrayList<>(tableNames.length);
+ for (String tableName : tableNames) {
+ configs.add(tableConfig(tableName, tableName.endsWith("products")));
+ }
+ return configs;
+ }
+
+ private Map<String, Object> tableConfig(String tableName, boolean withDescription) {
+ List<Map<String, Object>> columns = new ArrayList<>();
+ columns.add(column("id", "int"));
+ columns.add(column("name", "string"));
+ if (withDescription) {
+ columns.add(column("description", "string"));
+ }
+
+ Map<String, Object> primaryKey = new HashMap<>();
+ primaryKey.put("name", "pk_" + tableName.substring(tableName.indexOf('.') + 1));
+ primaryKey.put("columnNames", Collections.singletonList("id"));
+
+ Map<String, Object> schema = new HashMap<>();
+ schema.put("table", tableName);
+ schema.put("columns", columns);
+ schema.put("primaryKey", primaryKey);
+
+ Map<String, Object> tableConfig = new HashMap<>();
+ tableConfig.put("schema", schema);
+ return tableConfig;
+ }
+
+ private Map<String, Object> column(String name, String type) {
+ Map<String, Object> column = new HashMap<>();
+ column.put("name", name);
+ column.put("type", type);
+ return column;
+ }
+
+ private static List<CatalogTable> testTable() {
+ return Collections.singletonList(
+ createTable(
+ "test",
+ "products",
+ Arrays.asList(
+ physicalColumn("id", BasicType.INT_TYPE),
+ physicalColumn("name", BasicType.STRING_TYPE),
+ physicalColumn("description", BasicType.STRING_TYPE))));
+ }
+
+ private static List<CatalogTable> foreignTable() {
+ return Collections.singletonList(
+ createTable(
+ "other",
+ "products",
+ Collections.singletonList(physicalColumn("id", BasicType.INT_TYPE))));
+ }
+
+ private static CatalogTable createTable(
+ String keyspace, String tableName, List<PhysicalColumn> columns) {
+ TableSchema.Builder schemaBuilder =
+ TableSchema.builder()
+ .primaryKey(
+ PrimaryKey.of("pk_" + tableName, Collections.singletonList("id")));
+ columns.forEach(schemaBuilder::column);
+ return CatalogTable.of(
+ TableIdentifier.of(keyspace, TablePath.of(keyspace, tableName)),
+ schemaBuilder.build(),
+ Collections.emptyMap(),
+ Collections.emptyList(),
+ null);
+ }
+
+ private static PhysicalColumn physicalColumn(String name, BasicType<?> dataType) {
+ return PhysicalColumn.builder().name(name).dataType(dataType).build();
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/TestVitessSourceReaderIT.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/TestVitessSourceReaderIT.java
new file mode 100644
index 0000000000..a083a64c38
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/TestVitessSourceReaderIT.java
@@ -0,0 +1,431 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.reader;
+
+import org.apache.seatunnel.api.common.metrics.MetricsContext;
+import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.event.EventListener;
+import org.apache.seatunnel.api.options.ConnectorCommonOptions;
+import org.apache.seatunnel.api.source.Boundedness;
+import org.apache.seatunnel.api.source.Collector;
+import org.apache.seatunnel.api.source.SourceEvent;
+import org.apache.seatunnel.api.source.SourceReader;
+import org.apache.seatunnel.api.table.catalog.CatalogTable;
+import org.apache.seatunnel.api.table.catalog.PhysicalColumn;
+import org.apache.seatunnel.api.table.catalog.PrimaryKey;
+import org.apache.seatunnel.api.table.catalog.TableIdentifier;
+import org.apache.seatunnel.api.table.catalog.TablePath;
+import org.apache.seatunnel.api.table.catalog.TableSchema;
+import org.apache.seatunnel.api.table.type.BasicType;
+import org.apache.seatunnel.api.table.type.RowKind;
+import org.apache.seatunnel.api.table.type.SeaTunnelRow;
+import org.apache.seatunnel.connectors.cdc.base.option.SourceOptions;
+import org.apache.seatunnel.connectors.cdc.base.option.StartupMode;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceConfig;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.config.VitessSourceOptions;
+import org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.split.VitessSourceSplit;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.lifecycle.Startables;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+/** Integration tests that exercise stable startup, table identity and checkpoint restore. */
+class TestVitessSourceReaderIT {
+
+ private static final VitessContainer VITESS_CONTAINER =
+ new VitessContainer()
+ .withKeyspace("test")
+ .withExposedPorts(VitessContainer.MYSQL_PORT, VitessContainer.GRPC_PORT);
+
+ @BeforeAll
+ static void startContainer() {
+ Startables.deepStart(Stream.of(VITESS_CONTAINER)).join();
+ }
+
+ @AfterAll
+ static void stopContainer() {
+ VITESS_CONTAINER.stop();
+ }
+
+ @BeforeEach
+ void initializeTables() throws Exception {
+ executeStatements(
+ "USE test",
+ "DROP TABLE IF EXISTS customers",
+ "DROP TABLE IF EXISTS products",
+ "CREATE TABLE products ("
+ + "id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,"
+ + "name VARCHAR(255) NOT NULL,"
+ + "description VARCHAR(512),"
+ + "weight FLOAT)",
+ "ALTER TABLE products AUTO_INCREMENT = 101",
+ "CREATE TABLE customers ("
+ + "id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,"
+ + "name VARCHAR(255) NOT NULL)",
+ "ALTER TABLE customers AUTO_INCREMENT = 201");
+ }
+
+ @Test
+ void testCheckpointRestorePreservesOffsetsAndTableIdentity() throws Exception {
+ ReadonlyConfig config =
+ createConfig(
+ StartupMode.LATEST, null, Arrays.asList("test.products", "test.customers"));
+ List<CatalogTable> catalogTables = Arrays.asList(productTable(), customerTable());
+
+ VitessSourceConfig sourceConfig = VitessSourceConfig.of(config, catalogTables);
+ VitessSourceReader reader =
+ new VitessSourceReader(new TestingSourceReaderContext(), sourceConfig);
+ reader.open();
+ reader.addSplits(Collections.singletonList(sourceConfig.createInitialSplit()));
+ waitForVitessStreamStartup();
+
+ TestingCollector collector = new TestingCollector();
+ emitUntilRowObserved(
+ reader,
+ collector,
+ "INSERT INTO products VALUES (default, 'scooter', 'Small 2-wheel scooter', 3.14)",
+ row ->
+ "test.products".equals(row.getTableId())
+ && "scooter".equals(row.getField(1)));
+ emitUntilRowObserved(
+ reader,
+ collector,
+ "INSERT INTO customers VALUES (default, 'alice')",
+ row ->
+ "test.customers".equals(row.getTableId())
+ && "alice".equals(row.getField(1)));
+
+ Assertions.assertTrue(
+ collector.rows.stream()
+ .anyMatch(
+ row ->
+ "test.products".equals(row.getTableId())
+ && RowKind.INSERT.equals(row.getRowKind())
+ && "scooter".equals(row.getField(1))));
+ Assertions.assertTrue(
+ collector.rows.stream()
+ .anyMatch(
+ row ->
+ "test.customers".equals(row.getTableId())
+ && "alice".equals(row.getField(1))));
+
+ List<VitessSourceSplit> checkpointSplits = reader.snapshotState(1L);
+ Assertions.assertEquals(1, checkpointSplits.size());
+ Assertions.assertNotNull(checkpointSplits.get(0).getOffset());
+ Assertions.assertTrue(checkpointSplits.get(0).getOffset().containsKey("vgtid"));
+ Assertions.assertNotNull(checkpointSplits.get(0).getTableSchemas());
+ Assertions.assertEquals(2, checkpointSplits.get(0).getTableSchemas().size());
+ reader.close();
+
+ executeStatements(
+ "INSERT INTO products VALUES (default, 'car battery', '12V car battery', 8.1)");
+
+ VitessSourceReader restoredReader =
+ new VitessSourceReader(new TestingSourceReaderContext(), sourceConfig);
+ restoredReader.open();
+ restoredReader.addSplits(checkpointSplits);
+ waitForVitessStreamStartup();
+
+ TestingCollector restoredCollector = new TestingCollector();
+ waitUntilRowMatches(
+ restoredReader,
+ restoredCollector,
+ row ->
+ "test.products".equals(row.getTableId())
+ && "car battery".equals(row.getField(1)));
+
+ Assertions.assertTrue(
+ restoredCollector.rows.stream()
+ .anyMatch(
+ row ->
+ "test.products".equals(row.getTableId())
+ && "car battery".equals(row.getField(1))));
+ restoredReader.close();
+ }
+
+ @Test
+ void testSpecificStartupUsesCapturedVgtid() throws Exception {
+ ReadonlyConfig latestConfig =
+ createConfig(StartupMode.LATEST, null, Collections.singletonList("test.products"));
+ VitessSourceConfig latestSourceConfig =
+ VitessSourceConfig.of(latestConfig, Collections.singletonList(productTable()));
+ VitessSourceReader bootstrapReader =
+ new VitessSourceReader(new TestingSourceReaderContext(), latestSourceConfig);
+ bootstrapReader.open();
+ bootstrapReader.addSplits(
+ Collections.singletonList(latestSourceConfig.createInitialSplit()));
+ waitForVitessStreamStartup();
+
+ TestingCollector bootstrapCollector = new TestingCollector();
+ emitUntilRowObserved(
+ bootstrapReader,
+ bootstrapCollector,
+ "INSERT INTO products VALUES (default, 'scooter', 'Small 2-wheel scooter', 3.14)",
+ row ->
+ "test.products".equals(row.getTableId())
+ && "scooter".equals(row.getField(1)));
+ List<VitessSourceSplit> bootstrapCheckpointSplits = bootstrapReader.snapshotState(1L);
+ String capturedVgtid = (String) bootstrapCheckpointSplits.get(0).getOffset().get("vgtid");
+ Assertions.assertNotNull(bootstrapCheckpointSplits.get(0).getTableSchemas());
+ bootstrapReader.close();
+
+ executeStatements(
+ "INSERT INTO products VALUES (default, 'hammer', '16oz carpenters hammer', 1.0)");
+
+ ReadonlyConfig specificConfig =
+ createConfig(
+ StartupMode.SPECIFIC,
+ capturedVgtid,
+ Collections.singletonList("test.products"));
+ VitessSourceConfig specificSourceConfig =
+ VitessSourceConfig.of(specificConfig, Collections.singletonList(productTable()));
+ VitessSourceReader specificReader =
+ new VitessSourceReader(new TestingSourceReaderContext(), specificSourceConfig);
+ specificReader.open();
+ VitessSourceSplit specificSplit = specificSourceConfig.createInitialSplit();
+ Assertions.assertNotNull(specificSplit.getTableSchemas());
+ specificReader.addSplits(Collections.singletonList(specificSplit));
+ waitForVitessStreamStartup();
+
+ TestingCollector specificCollector = new TestingCollector();
+ waitUntilRowMatches(
+ specificReader,
+ specificCollector,
+ row ->
+ "test.products".equals(row.getTableId())
+ && "hammer".equals(row.getField(1)));
+
+ Assertions.assertTrue(
+ specificCollector.rows.stream()
+ .anyMatch(
+ row ->
+ "test.products".equals(row.getTableId())
+ && "hammer".equals(row.getField(1))));
+ specificReader.close();
+ }
+
+ private static CatalogTable productTable() {
+ TableSchema tableSchema =
+ TableSchema.builder()
+ .primaryKey(PrimaryKey.of("pk_products", Collections.singletonList("id")))
+ .column(
+ PhysicalColumn.builder()
+ .name("id")
+ .dataType(BasicType.INT_TYPE)
+ .build())
+ .column(
+ PhysicalColumn.builder()
+ .name("name")
+ .dataType(BasicType.STRING_TYPE)
+ .build())
+ .column(
+ PhysicalColumn.builder()
+ .name("description")
+ .dataType(BasicType.STRING_TYPE)
+ .build())
+ .column(
+ PhysicalColumn.builder()
+ .name("weight")
+ .dataType(BasicType.FLOAT_TYPE)
+ .build())
+ .build();
+ return CatalogTable.of(
+ TableIdentifier.of("test", TablePath.of("test", "products")),
+ tableSchema,
+ Collections.emptyMap(),
+ Collections.emptyList(),
+ null);
+ }
+
+ private static CatalogTable customerTable() {
+ TableSchema tableSchema =
+ TableSchema.builder()
+ .primaryKey(PrimaryKey.of("pk_customers", Collections.singletonList("id")))
+ .column(
+ PhysicalColumn.builder()
+ .name("id")
+ .dataType(BasicType.INT_TYPE)
+ .build())
+ .column(
+ PhysicalColumn.builder()
+ .name("name")
+ .dataType(BasicType.STRING_TYPE)
+ .build())
+ .build();
+ return CatalogTable.of(
+ TableIdentifier.of("test", TablePath.of("test", "customers")),
+ tableSchema,
+ Collections.emptyMap(),
+ Collections.emptyList(),
+ null);
+ }
+
+ private static ReadonlyConfig createConfig(
+ StartupMode startupMode, String specificVgtid, List<String> tableNames) {
+ Map<String, Object> options = new HashMap<>();
+ options.put(VitessSourceOptions.HOSTNAME.key(), VITESS_CONTAINER.getHost());
+ options.put(VitessSourceOptions.PORT.key(), VITESS_CONTAINER.getGrpcPort());
+ options.put(VitessSourceOptions.KEYSPACE.key(), VITESS_CONTAINER.getKeyspace());
+ options.put(VitessSourceOptions.STARTUP_MODE.key(), startupMode.name());
+ options.put(ConnectorCommonOptions.TABLE_NAMES.key(), tableNames);
+ options.put(VitessSourceOptions.SERVER_TIME_ZONE.key(), "UTC");
+ options.put(
+ SourceOptions.DEBEZIUM_PROPERTIES.key(),
+ Collections.singletonMap("poll.interval.ms", "100"));
+ if (specificVgtid != null) {
+ options.put(VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID.key(), specificVgtid);
+ }
+ return ReadonlyConfig.fromMap(options);
+ }
+
+ private static void executeStatements(String... sqlStatements) throws Exception {
+ try (Connection connection = DriverManager.getConnection(VITESS_CONTAINER.getJdbcUrl());
+ Statement statement = connection.createStatement()) {
+ for (String sqlStatement : sqlStatements) {
+ statement.execute(sqlStatement);
+ }
+ }
+ }
+
+ private static void emitUntilRowObserved(
+ VitessSourceReader reader,
+ TestingCollector collector,
+ String sqlStatement,
+ Predicate<SeaTunnelRow> predicate)
+ throws Exception {
+ long deadline = System.currentTimeMillis() + 30_000L;
+ while (System.currentTimeMillis() < deadline) {
+ executeStatements(sqlStatement);
+ if (waitUntilRowMatches(reader, collector, predicate, 5_000L)) {
+ return;
+ }
+ }
+ Assertions.fail(
+ "Timed out waiting for Vitess CDC rows after repeated inserts. "
+ + "collectorRows="
+ + collectorDebug(collector));
+ }
+
+ private static void waitUntilRowMatches(
+ VitessSourceReader reader,
+ TestingCollector collector,
+ Predicate<SeaTunnelRow> predicate)
+ throws Exception {
+ Assertions.assertTrue(
+ waitUntilRowMatches(reader, collector, predicate, 30_000L),
+ "Timed out waiting for Vitess CDC rows.");
+ }
+
+ private static boolean waitUntilRowMatches(
+ VitessSourceReader reader,
+ TestingCollector collector,
+ Predicate<SeaTunnelRow> predicate,
+ long timeoutMillis)
+ throws Exception {
+ long deadline = System.currentTimeMillis() + timeoutMillis;
+ while (System.currentTimeMillis() < deadline) {
+ reader.pollNext(collector);
+ if (collector.rows.stream().anyMatch(predicate)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Flink CDC waits until the Debezium task reports a fully started state before producing test
+ * changes. SeaTunnel's source-reader abstraction does not expose that signal, so the IT keeps
+ * the same startup budget with a fixed warm-up window.
+ */
+ private static void waitForVitessStreamStartup() throws InterruptedException {
+ Thread.sleep(10_000L);
+ }
+
+ private static String collectorDebug(TestingCollector collector) {
+ if (collector.rows.isEmpty()) {
+ return "[]";
+ }
+ int fromIndex = Math.max(0, collector.rows.size() - 5);
+ return collector.rows.subList(fromIndex, collector.rows.size()).toString();
+ }
+
+ /** Minimal source reader context used by the integration tests. */
+ static final class TestingSourceReaderContext implements SourceReader.Context {
+
+ @Override
+ public int getIndexOfSubtask() {
+ return 0;
+ }
+
+ @Override
+ public Boundedness getBoundedness() {
+ return Boundedness.UNBOUNDED;
+ }
+
+ @Override
+ public void signalNoMoreElement() {}
+
+ @Override
+ public void sendSplitRequest() {}
+
+ @Override
+ public void sendSourceEventToEnumerator(SourceEvent sourceEvent) {}
+
+ @Override
+ public MetricsContext getMetricsContext() {
+ return null;
+ }
+
+ @Override
+ public EventListener getEventListener() {
+ return null;
+ }
+ }
+
+ /** Collector used by the integration tests to capture emitted SeaTunnel CDC rows. */
+ static final class TestingCollector implements Collector<SeaTunnelRow> {
+
+ private final Object checkpointLock = new Object();
+ private final List<SeaTunnelRow> rows = new ArrayList<>();
+
+ @Override
+ public void collect(SeaTunnelRow record) {
+ rows.add(record.copy());
+ }
+
+ @Override
+ public Object getCheckpointLock() {
+ return checkpointLock;
+ }
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessContainer.java b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessContainer.java
new file mode 100644
index 0000000000..488e70bed6
--- /dev/null
+++ b/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/test/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/reader/VitessContainer.java
@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.seatunnel.connectors.seatunnel.cdc.vitess.source.reader;
+
+import org.testcontainers.containers.JdbcDatabaseContainer;
+
+/** Minimal Testcontainers wrapper around Vitess vttestserver. */
+public class VitessContainer extends JdbcDatabaseContainer<VitessContainer> {
+
+ public static final String IMAGE = "vitess/vttestserver";
+ public static final String DEFAULT_TAG = "v17.0.2-mysql80";
+ public static final Integer VITESS_PORT = 15991;
+ public static final Integer GRPC_PORT = VITESS_PORT + 1;
+ public static final Integer MYSQL_PORT = VITESS_PORT + 3;
+
+ private String keyspace = "test";
+
+ public VitessContainer() {
+ this(DEFAULT_TAG);
+ }
+
+ public VitessContainer(String tag) {
+ super(IMAGE + ":" + tag);
+ }
+
+ @Override
+ protected void configure() {
+ addEnv("PORT", VITESS_PORT.toString());
+ addEnv("KEYSPACES", keyspace);
+ addEnv("NUM_SHARDS", "1");
+ addEnv("MYSQL_BIND_HOST", "0.0.0.0");
+ }
+
+ @Override
+ public String getDriverClassName() {
+ return "com.mysql.cj.jdbc.Driver";
+ }
+
+ @Override
+ public String getJdbcUrl() {
+ return "jdbc:mysql://" + getHost() + ":" + getMysqlPort() + "/" + keyspace;
+ }
+
+ @Override
+ public String getUsername() {
+ return "";
+ }
+
+ @Override
+ public String getPassword() {
+ return "";
+ }
+
+ public Integer getGrpcPort() {
+ return getMappedPort(GRPC_PORT);
+ }
+
+ public Integer getMysqlPort() {
+ return getMappedPort(MYSQL_PORT);
+ }
+
+ public String getKeyspace() {
+ return keyspace;
+ }
+
+ @Override
+ protected String getTestQueryString() {
+ return "SELECT 1";
+ }
+
+ public VitessContainer withKeyspace(String keyspace) {
+ this.keyspace = keyspace;
+ return this;
+ }
+}
diff --git a/seatunnel-connectors-v2/connector-cdc/pom.xml b/seatunnel-connectors-v2/connector-cdc/pom.xml
index 4d867d0625..652201859e 100644
--- a/seatunnel-connectors-v2/connector-cdc/pom.xml
+++ b/seatunnel-connectors-v2/connector-cdc/pom.xml
@@ -38,6 +38,7 @@
<module>connector-cdc-oracle</module>
<module>connector-cdc-opengauss</module>
<module>connector-cdc-tidb</module>
+ <module>connector-cdc-vitess</module>
</modules>
<properties>
diff --git a/seatunnel-dist/pom.xml b/seatunnel-dist/pom.xml
index 92d25d8aa8..afe4ca33f7 100644
--- a/seatunnel-dist/pom.xml
+++ b/seatunnel-dist/pom.xml
@@ -580,6 +580,12 @@
<version>${project.version}</version>
<scope>provided</scope>
</dependency>
+ <dependency>
+ <groupId>org.apache.seatunnel</groupId>
+ <artifactId>connector-cdc-vitess</artifactId>
+ <version>${project.version}</version>
+ <scope>provided</scope>
+ </dependency>
<dependency>
<groupId>org.apache.seatunnel</groupId>
<artifactId>connector-cdc-postgres</artifactId>