This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-12505-bc39c16cb0980b9f6ee310f54dc62efe809f1e7d in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit 9a4d3e13a5821d2ca12f18476613afb623d454eb Author: hutiefang76 <[email protected]> AuthorDate: Mon Sep 28 15:11:55 2026 +0000 [Docs][Connector-V2] Correct DuckDB XA support claim (#12505) --- docs/en/connectors/sink/DuckDB.md | 53 ++++++--------------------------------- docs/zh/connectors/sink/DuckDB.md | 48 ++++------------------------------- 2 files changed, 13 insertions(+), 88 deletions(-) diff --git a/docs/en/connectors/sink/DuckDB.md b/docs/en/connectors/sink/DuckDB.md index d2f8ab1a5a..e44679be70 100644 --- a/docs/en/connectors/sink/DuckDB.md +++ b/docs/en/connectors/sink/DuckDB.md @@ -16,9 +16,9 @@ import ChangeLog from '../changelog/connector-jdbc.md'; ## Description -Write data to a DuckDB database file through JDBC. Supports batch and streaming modes, supports concurrent -writing, and supports exactly-once semantics when the underlying JDBC driver exposes an XA datasource -(set `is_exactly_once = true` and provide `xa_data_source_class_name`). DuckDB runs in-process, so the connector +Write data to a DuckDB database file through JDBC. Supports batch and streaming modes and concurrent +writing. The DuckDB JDBC driver used by this connector does not provide an XA datasource, so the JDBC sink's +XA-based exactly-once option is unavailable for DuckDB. DuckDB runs in-process, so the connector works against a local database file path (`jdbc:duckdb:/path/to/database.db`) or an in-memory database. ## Using Dependency @@ -33,11 +33,11 @@ works against a local database file path (`jdbc:duckdb:/path/to/database.db`) or ## Key Features -- [x] [exactly-once](../../introduction/concepts/connector-v2-features.md) +- [ ] [exactly-once](../../introduction/concepts/connector-v2-features.md) - [x] [cdc](../../introduction/concepts/connector-v2-features.md) -> Use `Xa transactions` to ensure `exactly-once`. So only support `exactly-once` for the database which is -> support `Xa transactions`. You can set `is_exactly_once=true` to enable it. +> The generic JDBC sink implements exactly-once through XA transactions. The DuckDB JDBC driver does not +> provide an XA datasource; do not set `is_exactly_once = true` for DuckDB. - [ ] [timer flush](../../introduction/concepts/connector-v2-features.md) ## Supported DataSource Info @@ -78,9 +78,9 @@ works against a local database file path (`jdbc:duckdb:/path/to/database.db`) or | connection_check_timeout_sec | Int | No | 30 | The time in seconds to wait for the database operation used to validate the connection to complete. | | max_retries | Int | No | 0 | The number of retries to submit a failed `executeBatch` call. | | batch_size | Int | No | 1000 | For batch writing, when the number of buffered records reaches `batch_size` or the time reaches `checkpoint.interval`, the data is flushed into the database. | -| is_exactly_once | Boolean | No | false | Whether to enable exactly-once semantics, which uses XA transactions. When enabled, you must also set `xa_data_source_class_name`. | +| is_exactly_once | Boolean | No | false | Generic JDBC XA option. Keep `false` for DuckDB because its JDBC driver has no XA datasource. | | generate_sink_sql | Boolean | No | false | Generate SQL statements based on the database table you want to write to. Requires `database` and `table` (or `table_list`) to be configured. | -| xa_data_source_class_name | String | No | - | The XA datasource class name of the database driver. For DuckDB, use `org.duckdb.DuckDBXADataSource`. | +| xa_data_source_class_name | String | No | - | Generic JDBC XA datasource class option. The DuckDB JDBC driver does not provide one, so this option cannot enable exactly-once for DuckDB. | | max_commit_attempts | Int | No | 3 | The number of retries for transaction commit failures. | | transaction_timeout_sec | Int | No | -1 | The timeout after the transaction is opened, the default is `-1` (never timeout). Note that setting the timeout may affect exactly-once semantics. | | auto_commit | Boolean | No | true | Whether to enable automatic transaction commit. Set to `false` when `is_exactly_once = true`. | @@ -167,43 +167,6 @@ sink { } ``` -### Exactly-Once - -```hocon -env { - parallelism = 1 - job.mode = "BATCH" -} - -source { - FakeSource { - parallelism = 1 - row_num = 1000 - schema = { - fields { - id = "int" - name = "string" - age = "int" - email = "string" - } - } - } -} - -sink { - Jdbc { - url = "jdbc:duckdb:/tmp/test.db" - driver = "org.duckdb.DuckDBDriver" - table = "sink_table" - username = "" - password = "" - - is_exactly_once = "true" - - xa_data_source_class_name = "org.duckdb.DuckDBXADataSource" - } -} -``` ## Changelog diff --git a/docs/zh/connectors/sink/DuckDB.md b/docs/zh/connectors/sink/DuckDB.md index 6cf6ff41fd..63edfc6d7b 100644 --- a/docs/zh/connectors/sink/DuckDB.md +++ b/docs/zh/connectors/sink/DuckDB.md @@ -16,7 +16,7 @@ import ChangeLog from '../changelog/connector-jdbc.md'; ## 描述 -通过 JDBC 将数据写入 DuckDB 数据库文件。支持批处理和流处理两种模式，支持并发写入，在底层 JDBC 驱动提供 XA 数据源时支持精确一次语义（设置 `is_exactly_once = true` 并配置 `xa_data_source_class_name`）。DuckDB 是进程内数据库，因此连接器对接的是本地数据库文件路径（`jdbc:duckdb:/path/to/database.db`）或内存数据库。 +通过 JDBC 将数据写入 DuckDB 数据库文件。支持批处理和流处理两种模式，也支持并发写入。此连接器使用的 DuckDB JDBC 驱动没有提供 XA 数据源，因此 DuckDB 无法使用 JDBC Sink 基于 XA 的精确一次选项。DuckDB 是进程内数据库，因此连接器对接的是本地数据库文件路径（`jdbc:duckdb:/path/to/database.db`）或内存数据库。 ## 需要的依赖项 @@ -30,10 +30,10 @@ import ChangeLog from '../changelog/connector-jdbc.md'; ## 主要功能 -- [x] [精确一次](../../introduction/concepts/connector-v2-features.md) +- [ ] [精确一次](../../introduction/concepts/connector-v2-features.md) - [x] [CDC](../../introduction/concepts/connector-v2-features.md) -> 使用 `Xa 事务` 来确保 `精确一次`。因此只支持支持 `Xa 事务` 的数据库的 `精确一次`。您可以设置 `is_exactly_once=true` 来启用它。 +> 通用 JDBC Sink 通过 XA 事务实现精确一次；DuckDB JDBC 驱动没有 XA 数据源。DuckDB 作业不要设置 `is_exactly_once = true`。 ## 支持的数据源信息 @@ -73,9 +73,9 @@ import ChangeLog from '../changelog/connector-jdbc.md'; | connection_check_timeout_sec | Int | 否 | 30 | 等待用于验证连接的数据库操作完成的时间（以秒为单位）。 | | max_retries | Int | 否 | 0 | 提交失败（executeBatch）的重试次数 | | batch_size | Int | 否 | 1000 | 对于批量写入，当缓冲记录数达到 `batch_size` 数量或时间达到 `checkpoint.interval`<br/>时，数据将被刷新到数据库中 | -| is_exactly_once | Boolean | 否 | false | 是否启用精确一次语义，将使用 Xa 事务。如果开启，您需要<br/>设置 `xa_data_source_class_name`。 | +| is_exactly_once | Boolean | 否 | false | 通用 JDBC 的 XA 选项。DuckDB JDBC 驱动没有 XA 数据源，应保持 `false`。 | | generate_sink_sql | Boolean | 否 | false | 根据您要写入的数据库表生成 sql 语句 | -| xa_data_source_class_name | String | 否 | - | 数据库驱动程序的 xa 数据源类名，例如，DuckDB 是 `org.duckdb.DuckDBXADataSource`，<br/>其他数据源请参考附录 | +| xa_data_source_class_name | String | 否 | - | 通用 JDBC 的 XA 数据源类名选项。DuckDB JDBC 驱动没有提供该类，不能借此为 DuckDB 启用精确一次。 | | max_commit_attempts | Int | 否 | 3 | 事务提交失败的重试次数 | | transaction_timeout_sec | Int | 否 | -1 | 事务打开后的超时时间，默认为 -1（永不超时）。请注意，设置超时可能会影响<br/>精确一次语义 | | auto_commit | Boolean | 否 | true | 默认启用自动事务提交 | @@ -163,44 +163,6 @@ sink { } ``` -### 精确一次 - -``` -env { - parallelism = 1 - job.mode = "BATCH" -} - -source { - FakeSource { - parallelism = 1 - row_num = 1000 - schema = { - fields { - id = "int" - name = "string" - age = "int" - email = "string" - } - } - } -} - -sink { - Jdbc { - url = "jdbc:duckdb:/tmp/test.db" - driver = "org.duckdb.DuckDBDriver" - table = "sink_table" - username = "" - password = "" - - is_exactly_once = "true" - - xa_data_source_class_name = "org.duckdb.DuckDBXADataSource" - } -} -``` - ## Changelog <ChangeLog />
