> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema 变更传播支持

> 说明 ClickPipes 可在源表中检测到的 schema 变更类型的页面

MySQL 的 ClickPipes 可以检测源表中的 schema 变更，并且在某些情况下会自动将这些变更传播到目标端表。下文说明了各类 DDL 操作的处理方式：

[//]: # "TODO 补充此页面：rename、数据类型变更以及 truncate 的处理行为，并提供如何处理不兼容 schema 变更的指导。"

| Schema 变更类型                                          | 行为                                                                                                                    |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 添加新列 (`ALTER TABLE ADD COLUMN ...`)                  | 自动传播。schema 变更后复制的所有行都会包含新列                                                                                           |
| 添加带默认值的新列 (`ALTER TABLE ADD COLUMN ... DEFAULT ...`) | 自动传播。[支持的默认值](#default-values-for-added-columns)也会添加到 ClickHouse 列中，因此这些默认值既适用于 ClickHouse 中已有的行，也适用于 schema 变更后复制的行。 |
| 删除现有列 (`ALTER TABLE DROP COLUMN ...`)                | 可以检测到，但**不会**传播。对于 schema 变更后复制的所有行，被删除的列将填充为 `NULL`                                                                  |

<Note>
  当前不支持在 snapshot 期间添加列。建议的变通方法是在计划中的 schema 变更之前或之后执行 snapshot；或者，如果 ClickPipe 已经失败，可手动向目标端表添加一个类型合适的列。
</Note>

<div id="default-values-for-added-columns">
  ## 新增列的默认值
</div>

对于新增列，ClickPipes 仅在能够安全地将该值转换为 ClickHouse 支持的形式时才会传播默认值。传播后，ClickHouse 会在读取早于新列的数据分区片段时使用该默认值。因此，ClickHouse 中已有的行无需完整刷新表即可获得源端默认值。

ClickPipes 会传播整数字面量、小数字面量和浮点数字面量、布尔值、简单的字符串和日期值；当 MySQL 服务器提供完整的 binlog 行元数据时，还会传播枚举或集合值。它会使用与 ClickHouse 兼容的引号规则重写字符串字面量。

ClickPipes 会特意省略并非可移植字面量的默认值，包括 `NULL`、比特字面量、`CURRENT_TIMESTAMP`、`NOW()` 或 `UUID()` 等函数调用，以及包含反斜杠或控制字符的字符串值。该列仍会被添加，但对于早于该列的数据分区片段，ClickHouse 会使用相应类型的常规默认值。如果这些现有行必须包含源端默认值，则需要完整刷新表。

ClickPipes 仅在执行 `ALTER TABLE ADD COLUMN` 时传播默认值。后续更改或移除列默认值的操作不会传播到 ClickHouse。

<div id="mysql-5-limitations">
  ### MySQL 5.x 限制
</div>

早于 [8.0.1](https://dev.mysql.com/blog-archive/more-metadata-is-written-into-binary-log/) 的 MySQL 版本不会在 binlog 中包含完整的列元数据 (`binlog_row_metadata=FULL`) ，因此 ClickPipes 会按列的序号跟踪列。这意味着：

* **在末尾添加列** (`ALTER TABLE ADD COLUMN ...`) 受支持。
* **任何会导致列位置移位的 DDL** 都会导致管道报错，因为届时将无法再可靠地按序号进行映射。这包括：
  * `ALTER TABLE DROP COLUMN ...`
  * `ALTER TABLE ADD COLUMN ... AFTER ...` / `FIRST`
  * `ALTER TABLE MODIFY COLUMN ... AFTER ...` / `FIRST`
  * `ALTER TABLE CHANGE COLUMN ... AFTER ...` / `FIRST`

如果遇到此错误，您需要重新同步该管道。