Ecosystem Integration: mysql_fdw

CN/modules/ROOT/nav.adoc

@@ -76,6 +76,7 @@
 *** xref:master/ecosystem_components/zhparser.adoc[zhparser]
 *** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
 *** xref:master/ecosystem_components/set_user.adoc[set_user]
+*** xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw]
 * 监控运维
 ** xref:master/getting-started/daily_monitoring.adoc[日常监控]
 ** xref:master/getting-started/daily_maintenance.adoc[日常维护]

CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc

@@ -41,6 +41,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
 | 28 | xref:master/ecosystem_components/zhparser.adoc[zhparser] | master branch | 用于中文全文搜索的PostgreSQL插件，基于SCWS（即：简易中文分词系统）实现了一个中文解析器 | 搜索引擎、关键字提取
 | 29 | xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | 可靠的 PostgreSQL 备份和恢复解决方案 | 容灾备份、大库备份、异地/多层容灾
 | 30 | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL 安全审计扩展，可控角色切换，支持白名单、强制审计、拦截高危操作 | 可控角色切换、权限管理、审计日志
+| 31 | xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw] | 2.9.3 | 用于从 IvorySQL 查询和修改 MySQL 数据的外部数据包装器，支持模式导入和查询下推 | MySQL 集成、联邦查询、数据迁移
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

CN/modules/ROOT/pages/master/ecosystem_components/mysql_fdw.adoc

@@ -0,0 +1,132 @@
+:sectnums:
+:sectnumlevels: 5
+
+= mysql_fdw
+
+== 概述
+
+mysql_fdw 是用于 MySQL 的 PostgreSQL 外部数据包装器。它让 IvorySQL 可以通过 SQL 查询和修改 MySQL 表，支持 `IMPORT FOREIGN SCHEMA`，并可将过滤、投影、连接、聚合、排序和 LIMIT 下推到远端执行。
+
+项目地址：<https://github.com/EnterpriseDB/mysql_fdw>
+
+测试版本：2.9.3
+
+许可证：PostgreSQL License
+
+== 兼容性
+
+已在 x86_64 Linux 上验证以下组合：
+
+[cols="1,1"]
+|===
+| 组件 | 版本
+| IvorySQL | 当前 `IVORY_REL_5_STABLE`（IvorySQL 5.6 / PostgreSQL 18.6）
+| mysql_fdw | 2.9.3
+| MySQL Server | 8.4
+| MariaDB Connector/C | 3.1
+|===
+
+[IMPORTANT]
+mysql_fdw 2.9.3 依赖 IvorySQL PR #1448 恢复的 PostgreSQL 扩展 API。已发布的 IvorySQL 5.4 镜像早于该修复，编译该版本时会出现 `ExecTypeFromTL` 参数数量错误。请使用包含此修复的当前 `IVORY_REL_5_STABLE` 构建或更新版本的 IvorySQL。
+
+== 安装
+
+先安装 C 编译器、GNU make，以及 MySQL 或 MariaDB 客户端开发包，再显式指定目标 IvorySQL 进行编译：
+
+[source,bash]
+----
+git clone https://github.com/EnterpriseDB/mysql_fdw.git
+cd mysql_fdw
+git checkout REL-2_9_3
+
+# 请按实际安装位置修改，下面是 RPM 安装的默认路径。
+export IVORYSQL_HOME=/usr/ivory-5
+export PG_CONFIG="$IVORYSQL_HOME/bin/pg_config"
+make USE_PGXS=1 PG_CONFIG="$PG_CONFIG"
+sudo make USE_PGXS=1 PG_CONFIG="$PG_CONFIG" install
+----
+
+编译前用 `pg_config --version` 确认它指向 IvorySQL。该扩展不需要预加载或重启数据库。
+
+== 准备 MySQL
+
+[source,sql]
+----
+CREATE DATABASE fdw_test CHARACTER SET utf8mb4;
+CREATE USER 'fdw_user'@'%' IDENTIFIED BY 'fdw_pass';
+GRANT ALL PRIVILEGES ON fdw_test.* TO 'fdw_user'@'%';
+
+CREATE TABLE fdw_test.products (
+    id integer PRIMARY KEY,
+    name varchar(100),
+    price decimal(10,2),
+    note varchar(100)
+);
+INSERT INTO fdw_test.products VALUES
+    (1, 'IvorySQL', 99.50, '中文'),
+    (2, 'MySQL', 49.00, NULL);
+----
+
+== 配置和使用
+
+[source,sql]
+----
+CREATE EXTENSION mysql_fdw;
+
+CREATE SERVER mysql_server
+  FOREIGN DATA WRAPPER mysql_fdw
+  OPTIONS (host '127.0.0.1', port '3306', character_set 'utf8mb4');
+
+CREATE USER MAPPING FOR CURRENT_USER
+  SERVER mysql_server
+  OPTIONS (username 'fdw_user', password 'fdw_pass');
+
+CREATE SCHEMA mysql_remote;
+IMPORT FOREIGN SCHEMA fdw_test
+  FROM SERVER mysql_server INTO mysql_remote;
+
+SELECT * FROM mysql_remote.products ORDER BY id;
+INSERT INTO mysql_remote.products VALUES (3, 'FDW', 10.00, 'insert');
+UPDATE mysql_remote.products SET price = 11.00 WHERE id = 3;
+DELETE FROM mysql_remote.products WHERE id = 3;
+----
+
+远端数据库保存 UTF-8 文本时应设置 `character_set 'utf8mb4'`，否则非 ASCII 数据可能被错误解码。
+
+可用 `EXPLAIN VERBOSE` 检查下推，`Remote query` 字段会显示 mysql_fdw 能在远端执行的操作：
+
+[source,sql]
+----
+EXPLAIN (VERBOSE, COSTS OFF)
+SELECT name, price
+FROM mysql_remote.products
+WHERE price > 40
+ORDER BY price DESC
+LIMIT 1;
+----
+
+== 双模式验证
+
+同一组外表可在 IvorySQL 两种模式中使用：
+
+[source,sql]
+----
+SET ivorysql.compatible_mode = pg;
+SELECT * FROM mysql_remote.products ORDER BY id;
+
+SET ivorysql.compatible_mode = oracle;
+SELECT 1 FROM dual;
+SELECT * FROM mysql_remote.products ORDER BY id;
+INSERT INTO mysql_remote.products VALUES (4, 'Oracle mode', 20.00, NULL);
+UPDATE mysql_remote.products SET price = 21.00 WHERE id = 4;
+DELETE FROM mysql_remote.products WHERE id = 4;
+----
+
+验证覆盖扩展创建、导入模式、UTF-8 和 NULL 值、增删改查，以及两种模式下的过滤、投影、排序和 LIMIT 下推。mysql_fdw 的九组上游回归测试也全部通过：`server_options`、`connection_validation`、`dml`、`select`、`pushdown`、`join_pushdown`、`aggregate_pushdown`、`limit_offset_pushdown` 和 `misc`。
+
+== 故障排查
+
+* `too few arguments to function 'ExecTypeFromTL'`：IvorySQL 安装版本早于上述扩展 API 兼容性修复。
+* `Can't connect to MySQL server`：检查主机、端口、防火墙，以及 MySQL 账户是否允许 IvorySQL 所在主机连接。
+* 文本乱码：设置服务端选项 `character_set 'utf8mb4'`，并检查远端数据库字符集。
+* 生产环境不要在共享脚本中保存密码，并限制用户映射的访问权限。

EN/modules/ROOT/nav.adoc

@@ -76,6 +76,7 @@
 *** xref:master/ecosystem_components/zhparser_en.adoc[zhparser]
 *** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
 *** xref:master/ecosystem_components/set_user.adoc[set_user]
+*** xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw]
 * Monitor and O&M
 ** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
 ** xref:master/getting-started/daily_maintenance.adoc[Maintenance]

EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc

@@ -42,6 +42,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
 |*28*| xref:master/ecosystem_components/zhparser_en.adoc[zhparser] | master branch | PostgreSQL extension for full-text search of Chinese language (Mandarin Chinese). It implements a Chinese language parser base on the | Search engine、keyword extraction
 |*29*| xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | pgBackRest is a reliable backup and restore solution for PostgreSQL that seamlessly scales up to the largest databases and workloads | Disaster recovery backup, large database backup, off-site/multi-tier disaster recovery
 | *30* | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL security auditing extension with controlled role switching, supporting allowlists, enforced auditing, and blocking of high-risk operations | Controlled role switching, privilege management, audit logging
+|*31*| xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw] | 2.9.3 | Foreign data wrapper for querying and modifying MySQL data from IvorySQL, with schema import and query pushdown | MySQL integration, federated queries, data migration
 |====
 
 These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system.

EN/modules/ROOT/pages/master/ecosystem_components/mysql_fdw.adoc

@@ -0,0 +1,132 @@
+:sectnums:
+:sectnumlevels: 5
+
+= mysql_fdw
+
+== Overview
+
+mysql_fdw is a PostgreSQL foreign data wrapper for MySQL. It allows IvorySQL to query and modify MySQL tables through SQL, supports `IMPORT FOREIGN SCHEMA`, and can push filters, projections, joins, aggregates, sorting, and limits to the remote server.
+
+Project page: <https://github.com/EnterpriseDB/mysql_fdw>
+
+Tested version: 2.9.3
+
+License: PostgreSQL License
+
+== Compatibility
+
+The following combination was validated on x86_64 Linux:
+
+[cols="1,1"]
+|===
+| Component | Version
+| IvorySQL | current `IVORY_REL_5_STABLE` (IvorySQL 5.6 / PostgreSQL 18.6)
+| mysql_fdw | 2.9.3
+| MySQL Server | 8.4
+| MariaDB Connector/C | 3.1
+|===
+
+[IMPORTANT]
+mysql_fdw 2.9.3 requires the PostgreSQL-compatible extension APIs restored by IvorySQL PR #1448. The released IvorySQL 5.4 image predates that fix and fails to compile this version with an `ExecTypeFromTL` argument-count error. Use a current `IVORY_REL_5_STABLE` build containing that change or a newer IvorySQL release.
+
+== Installation
+
+Install a C compiler, GNU make, and the MySQL or MariaDB client development package. Then build against the intended IvorySQL installation explicitly:
+
+[source,bash]
+----
+git clone https://github.com/EnterpriseDB/mysql_fdw.git
+cd mysql_fdw
+git checkout REL-2_9_3
+
+# Adjust this to your IvorySQL installation (RPM default shown).
+export IVORYSQL_HOME=/usr/ivory-5
+export PG_CONFIG="$IVORYSQL_HOME/bin/pg_config"
+make USE_PGXS=1 PG_CONFIG="$PG_CONFIG"
+sudo make USE_PGXS=1 PG_CONFIG="$PG_CONFIG" install
+----
+
+Confirm that `pg_config --version` points to IvorySQL before building. No server preload or restart is required.
+
+== MySQL Preparation
+
+[source,sql]
+----
+CREATE DATABASE fdw_test CHARACTER SET utf8mb4;
+CREATE USER 'fdw_user'@'%' IDENTIFIED BY 'fdw_pass';
+GRANT ALL PRIVILEGES ON fdw_test.* TO 'fdw_user'@'%';
+
+CREATE TABLE fdw_test.products (
+    id integer PRIMARY KEY,
+    name varchar(100),
+    price decimal(10,2),
+    note varchar(100)
+);
+INSERT INTO fdw_test.products VALUES
+    (1, 'IvorySQL', 99.50, '中文'),
+    (2, 'MySQL', 49.00, NULL);
+----
+
+== IvorySQL Configuration and Use
+
+[source,sql]
+----
+CREATE EXTENSION mysql_fdw;
+
+CREATE SERVER mysql_server
+  FOREIGN DATA WRAPPER mysql_fdw
+  OPTIONS (host '127.0.0.1', port '3306', character_set 'utf8mb4');
+
+CREATE USER MAPPING FOR CURRENT_USER
+  SERVER mysql_server
+  OPTIONS (username 'fdw_user', password 'fdw_pass');
+
+CREATE SCHEMA mysql_remote;
+IMPORT FOREIGN SCHEMA fdw_test
+  FROM SERVER mysql_server INTO mysql_remote;
+
+SELECT * FROM mysql_remote.products ORDER BY id;
+INSERT INTO mysql_remote.products VALUES (3, 'FDW', 10.00, 'insert');
+UPDATE mysql_remote.products SET price = 11.00 WHERE id = 3;
+DELETE FROM mysql_remote.products WHERE id = 3;
+----
+
+Set `character_set 'utf8mb4'` when the remote database stores UTF-8 text; otherwise non-ASCII data can be decoded incorrectly.
+
+Use `EXPLAIN VERBOSE` to inspect pushdown. The `Remote query` field should contain operations that mysql_fdw can execute remotely:
+
+[source,sql]
+----
+EXPLAIN (VERBOSE, COSTS OFF)
+SELECT name, price
+FROM mysql_remote.products
+WHERE price > 40
+ORDER BY price DESC
+LIMIT 1;
+----
+
+== Dual-mode Validation
+
+The same foreign tables can be used in both IvorySQL modes:
+
+[source,sql]
+----
+SET ivorysql.compatible_mode = pg;
+SELECT * FROM mysql_remote.products ORDER BY id;
+
+SET ivorysql.compatible_mode = oracle;
+SELECT 1 FROM dual;
+SELECT * FROM mysql_remote.products ORDER BY id;
+INSERT INTO mysql_remote.products VALUES (4, 'Oracle mode', 20.00, NULL);
+UPDATE mysql_remote.products SET price = 21.00 WHERE id = 4;
+DELETE FROM mysql_remote.products WHERE id = 4;
+----
+
+Validation covered extension creation, schema import, UTF-8 and NULL values, CRUD, and filter/projection/order/limit pushdown in both modes. All nine upstream mysql_fdw regression groups also passed against a MySQL 8.4 server: `server_options`, `connection_validation`, `dml`, `select`, `pushdown`, `join_pushdown`, `aggregate_pushdown`, `limit_offset_pushdown`, and `misc`.
+
+== Troubleshooting
+
+* `too few arguments to function 'ExecTypeFromTL'`: the IvorySQL installation is older than the extension-API compatibility fix described above.
+* `Can't connect to MySQL server`: verify the host, port, firewall, and that the MySQL account accepts connections from the IvorySQL host.
+* Garbled text: set the server option `character_set 'utf8mb4'` and verify the remote database character set.
+* Keep credentials out of shared scripts and restrict access to user mappings in production.