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

> ClickPipes for MySQL に関するよくある質問。

# ClickPipes for MySQL よくある質問

<div id="does-the-clickpipe-support-mariadb">
  ### MySQL ClickPipe は MariaDB をサポートしていますか？
</div>

はい、MySQL ClickPipe は MariaDB 10.0 以降をサポートしています。設定は MySQL と非常によく似ており、デフォルトでは GTID レプリケーションを使用します。

<div id="mariadb-partial-row-event-unsupported">
  ### サポートされていない MariaDB の部分行イベントが原因でパイプが失敗するのはなぜですか？
</div>

MariaDB 12.3 以降では、binlog に[部分行イベント](https://mariadb.com/docs/server/server-management/server-monitoring-logs/binary-log/row-binlog-events#partial_rows_log_event)が出力されることがありますが、これはまだサポートされていません。

復旧するには、パイプを再同期してください。再発する可能性を減らすには、ソースの `binlog_row_event_fragment_threshold` 設定を引き上げ、断片化される行の変更を減らすこともできます。ただし、この値は `max_allowed_packet` 未満にしてください。断片化されていない単一の binlog イベントが `max_allowed_packet` を超えると、代わりにレプリケーションストリームが失敗します ([パイプが max\_allowed\_packet の binlog エラーで失敗するのはなぜですか？](#binlog-event-exceeded-max-allowed-packet)を参照) 。

<div id="mariadb-compressed-column-unsupported">
  ### 非対応の MariaDB の COMPRESSED カラムが原因で、パイプが失敗するのはなぜですか？
</div>

パイプが次のようなエラーで失敗する場合:

```text theme={null}
table <database>.<table> has MariaDB COMPRESSED column(s) [<columns>], which cannot be replicated via CDC;
convert them to a non-compressed type or remove the table from the mirror
```

これは、そのテーブルに MariaDB の [カラム圧縮](https://mariadb.com/kb/en/storage-engine-independent-column-compression/) (`COLUMN_FORMAT COMPRESSED`) を使用しているカラムが 1 つ以上あることを意味します。これらの値は binlog から復元できないため、該当するテーブルは CDC (変更データキャプチャ) ではレプリケートできません。

これを解決するには:

* **圧縮されたカラムをソース側で非圧縮の型に変更する** (またはそのテーブルをパイプから削除する) :
  ```sql theme={null}
  ALTER TABLE <table> MODIFY <column> <type>; -- COLUMN_FORMAT COMPRESSED を指定しない
  ```
* テーブルまたはパイプを再同期する

<div id="does-the-clickpipe-support-planetscale-vitess">
  ### MySQL ClickPipe は PlanetScale、Vitess、または TiDB をサポートしていますか？
</div>

いいえ、これらは MySQL の binlog API に対応していません。

<div id="how-is-replication-managed">
  ### レプリケーションはどのように管理されますか？
</div>

`GTID` と `FilePos` の両方のレプリケーションをサポートしています。Postgres とは異なり、オフセットを管理するためのスロットはありません。代わりに、MySQL サーバーで十分な binlog の保持期間を設定する必要があります。binlog 内のオフセットが無効になった場合 (*たとえば、mirror が長時間 Paused のままだった場合や、`FilePos` レプリケーションの使用中にデータベースのフェイルオーバーが発生した場合*) 、パイプを再同期する必要があります。非効率なクエリによってインジェストが遅れ、保持期間を超えてしまう可能性があるため、宛先テーブルに応じて materialized view を必ず最適化してください。

また、アクティビティのないデータベースでは、ClickPipes がより新しいオフセットに進めないままログファイルがローテーションされることもあります。定期的に更新される heartbeat table をセットアップする必要がある場合があります。

初期ロードの開始時に、開始位置となる binlog オフセットを記録します。CDC (変更データキャプチャ) を進めるには、初期ロードの完了時点でもこのオフセットが有効である必要があります。大量のデータを取り込む場合は、適切な binlog の保持期間を必ず設定してください。テーブルのセットアップ中は、高度な設定で大きなテーブルに対して *Use a custom partitioning key for initial load* を設定すると、1 つのテーブルを並列にロードできるため、初期ロードを高速化できます。

<div id="binlog-event-exceeded-max-allowed-packet">
  ### パイプが `max_allowed_packet` の binlog エラーで失敗するのはなぜですか？
</div>

パイプが次のようなエラーで失敗する場合:

```text theme={null}
MySQL execute error: ERROR 1236 (HY000): log event entry exceeded max_allowed_packet;
Increase max_allowed_packet on source
```

これは、単一のbinlogイベント (1件の行変更に対応) が、MySQL serverの[`max_allowed_packet`](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet)設定よりも大きいことを意味します。serverはこの上限を超えるイベントを送信できないため、binlogストリームの読み取りが中断され、CDC (変更データキャプチャ) が先に進めなくなります。

これは多くの場合、大きな`BLOB`、`TEXT`、または`JSON`の値を含む行が原因です。解決するには、次の対応を行ってください。

* **ログソース側で`max_allowed_packet`を増やします。** 最大の行変更サイズを上回る値に引き上げてください。通常は最大値の`1G`に設定して問題ありません。
  ```sql theme={null}
  SET GLOBAL max_allowed_packet = 1073741824; -- 1 GiB
  ```
  再起動後も設定が保持されるように、server configuration (例: `my.cnf` または DB パラメータグループ) にも設定してください。
* **単一の行が1Gを超える場合:** パイプを再同期します。

<div id="binlog-partial-json-unsupported">
  ### パイプが不完全な JSON binlog エラーで失敗するのはなぜですか？
</div>

パイプが次のようなエラーで失敗する場合：

```text theme={null}
Received a partial JSON update event while processing <database>.<table>; binlog_row_value_options must be disabled (set to '')
```

これは、ソース MySQL サーバーで [`binlog_row_value_options`](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_row_value_options) が `PARTIAL_JSON` に設定されていることを意味します。このオプションを有効にすると、MySQL は `JSON` カラムの更新を完全なドキュメントではなく、部分差分 (変更されたパスのみ) として記録します。ClickPipes はこれらの部分差分を適用できないため、CDC (変更データキャプチャ) を進行できません。

解決するには:

* **ソース側で `PARTIAL_JSON` を無効にします。** 値を空文字列に戻します:
  ```sql theme={null}
  SET GLOBAL binlog_row_value_options = '';
  ```
  再起動後も設定が維持されるよう、サーバー設定 (例: `my.cnf` または DB パラメータグループ) でもこの値をクリアします。
* **パイプを再同期**して、クリーンなオフセットからレプリケーションを再開します。

<div id="secure-transport-required">
  ### パイプが require\_secure\_transport エラーで失敗するのはなぜですか？
</div>

パイプが次のようなエラーで失敗する場合：

```text theme={null}
MySQL execute error: handleAuthResult: ERROR 3159 (HY000): Connections using insecure transport
are prohibited while --require_secure_transport=ON.
```

これは、ソースサーバーで [`require_secure_transport`](https://dev.mysql.com/doc/refman/8.4/en/server-system-variables.html#sysvar_require_secure_transport) が有効になっており、暗号化されていない接続をすべて拒否する一方で、ClickPipe では TLS が無効になっていることを意味します。RDS for MySQL では、これはインスタンスの [DB パラメータグループ](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/mysql-ssl-connections.require-ssl.html)で設定します。Aurora MySQL では、これは [DB クラスターパラメータグループ](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Security.html#AuroraMySQL.Security.SSL.RequireSSL)の設定であり、インスタンスパラメータグループでは設定できません。どちらも有効化に再起動は必要ありません。また、Aurora MySQL 8.4 ではデフォルトで `ON` ですが、バージョン 2 および 3 ではデフォルトで `OFF` です。そのため、問題なくレプリケーションしていたパイプでも、パラメータの変更やバージョンアップグレード後に、パイプ側に変更がなくても失敗し始めることがあります。

解決するには、次のいずれかを実行します。

* **パイプで TLS を再度有効にします。** パイプの **設定** で接続設定を開き、**TLS を無効化** トグルをオフにします。保存時に証明書エラーが表示される場合は、TLS ホストの設定、ルート CA のアップロード、または証明書検証をスキップする方法について、[MySQL への接続時に TLS 証明書の検証エラーが発生するのはなぜですか？](#tls-certificate-validation-error)を参照してください。
* **または、ソースで `require_secure_transport` を無効にします。** 暗号化されていない接続を環境で許容できる場合は、RDS では DB パラメータグループ、Aurora では DB クラスターパラメータグループで無効にします。

接続に成功すると、レプリケーションは停止した位置から再開されます。パイプが binlog の保持期間を超えて失敗していた場合 ([レプリケーションはどのように管理されますか？](#how-is-replication-managed)を参照) は、再同期する必要があります。

<div id="tls-certificate-validation-error">
  ### MySQL への接続時に TLS 証明書の検証エラーが発生するのはなぜですか？
</div>

MySQL に接続すると、`x509: certificate is not valid for any names` や `x509: certificate signed by unknown authority` のような証明書エラーが発生することがあります。これは、ClickPipes でデフォルトで TLS 暗号化が有効になっているためです。

これらの問題を解決するには、いくつかの方法があります。

1. **TLS Host フィールドを設定する** - 接続先のホスト名が証明書と異なる場合 (Endpoint Service 経由の AWS PrivateLink でよくあります) は、証明書の Common Name (CN) または Subject Alternative Name (SAN) に一致するように「TLS Host (optional)」を設定してください。

2. **Root CA をアップロードする** - 内部の認証局を使用している MySQL サーバーや、デフォルトのインスタンス単位 CA 構成を使用する Google Cloud SQL の場合に該当します。Google Cloud SQL 証明書へのアクセス方法の詳細については、[このセクション](/ja/integrations/clickpipes/mysql/source/gcp#download-root-ca-certificate-gcp-mysql)を参照してください。

3. **サーバー証明書を設定する** - すべての接続ホスト名を含むようにサーバーの SSL 証明書を更新し、信頼された認証局を使用してください。

4. **証明書の検証をスキップする** - セルフホストの MySQL または MariaDB では、デフォルト構成で自己署名証明書が作成されますが、ClickPipes ではこれを検証できません ([MySQL](https://dev.mysql.com/doc/refman/8.4/en/creating-ssl-rsa-files-using-mysql.html#creating-ssl-rsa-files-using-mysql-automatic)、[MariaDB](https://mariadb.com/kb/en/securing-connections-for-client-and-server/#enabling-tls-for-mariadb-server)) 。この証明書を使用すると通信中のデータは暗号化されますが、サーバーのなりすましリスクがあります。本番環境では適切に署名された証明書の使用を推奨しますが、この方法は一時的なインスタンスでのテストや、レガシーなインフラストラクチャへの接続には便利です。

<div id="do-you-support-schema-changes">
  ### スキーマ変更に対応していますか？
</div>

詳細については、[ClickPipes for MySQL: スキーマ変更の伝播サポート](/ja/integrations/clickpipes/mysql/schema-changes) ページを参照してください。

<div id="support-on-delete-cascade">
  ### MySQL の外部キーのカスケード削除 `ON DELETE CASCADE` のレプリケーションをサポートしていますか？
</div>

MySQL では[カスケード削除が処理される仕組み](https://dev.mysql.com/doc/refman/8.0/en/innodb-and-mysql-replication.html)上、これらは binlog に書き込まれません。そのため、ClickPipes (または任意の CDC (変更データキャプチャ) ツール) でこれらをレプリケーションすることはできません。これにより、データの不整合が発生する可能性があります。カスケード削除をサポートするには、代わりにトリガーを使用することを推奨します。

<div id="replicate-table-dot">
  ### ドットを含むテーブルをレプリケートできないのはなぜですか？
</div>

現在、PeerDB には制限があり、レプリケーション元のテーブル識別子 (つまりスキーマ名またはテーブル名) にドットが含まれている場合、レプリケーションはサポートされていません。PeerDB はドットで分割して解釈するため、その場合はどこまでがスキーマでどこからがテーブルかを判別できないためです。
この制限を回避できるよう、スキーマとテーブルを個別に入力できるようにする対応が進められています。

<div id="include-excluded-columns">
  ### 最初にレプリケーション対象から除外したカラムを後から含めることはできますか？
</div>

現時点ではまだサポートされていません。代わりに、含めたいカラムがある場合は、対象の[テーブルを再同期](/ja/integrations/clickpipes/mysql/table-resync)してください。