Skip to content

Commit 6b30d0c

Browse files
messere1messere1
committed
docs: add mysql_fdw ecosystem integration
1 parent 700c645 commit 6b30d0c

6 files changed

Lines changed: 265 additions & 1 deletion

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,8 @@
7575
*** xref:master/ecosystem_components/pg_readonly.adoc[pg_readonly]
7676
*** xref:master/ecosystem_components/zhparser.adoc[zhparser]
7777
*** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
78-
*** xref:master/ecosystem_components/set_user.adoc[set_user]
78+
*** xref:master/ecosystem_components/set_user.adoc[set_user]
79+
*** xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw]
7980
* 监控运维
8081
** xref:master/getting-started/daily_monitoring.adoc[日常监控]
8182
** xref:master/getting-started/daily_maintenance.adoc[日常维护]

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
4141
| 28 | xref:master/ecosystem_components/zhparser.adoc[zhparser] | master branch | 用于中文全文搜索的PostgreSQL插件，基于SCWS（即：简易中文分词系统）实现了一个中文解析器 | 搜索引擎、关键字提取
4242
| 29 | xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | 可靠的 PostgreSQL 备份和恢复解决方案 | 容灾备份、大库备份、异地/多层容灾
4343
| 30 | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL 安全审计扩展，可控角色切换，支持白名单、强制审计、拦截高危操作 | 可控角色切换、权限管理、审计日志
44+
| 31 | xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw] | 2.9.3 | 用于从 IvorySQL 查询和修改 MySQL 数据的外部数据包装器，支持模式导入和查询下推 | MySQL 集成、联邦查询、数据迁移
4445
|====
4546

4647
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= mysql_fdw
5+
6+
== 概述
7+
8+
mysql_fdw 是用于 MySQL 的 PostgreSQL 外部数据包装器。它让 IvorySQL 可以通过 SQL 查询和修改 MySQL 表，支持 `IMPORT FOREIGN SCHEMA`，并可将过滤、投影、连接、聚合、排序和 LIMIT 下推到远端执行。
9+
10+
项目地址：<https://github.com/EnterpriseDB/mysql_fdw>
11+
12+
测试版本：2.9.3
13+
14+
许可证：PostgreSQL License
15+
16+
== 兼容性
17+
18+
已在 x86_64 Linux 上验证以下组合：
19+
20+
[cols="1,1"]
21+
|===
22+
| 组件 | 版本
23+
| IvorySQL | 当前 `IVORY_REL_5_STABLE`（IvorySQL 5.6 / PostgreSQL 18.6）
24+
| mysql_fdw | 2.9.3
25+
| MySQL Server | 8.4
26+
| MariaDB Connector/C | 3.1
27+
|===
28+
29+
[IMPORTANT]
30+
mysql_fdw 2.9.3 依赖 IvorySQL PR #1448 恢复的 PostgreSQL 扩展 API。已发布的 IvorySQL 5.4 镜像早于该修复，编译该版本时会出现 `ExecTypeFromTL` 参数数量错误。请使用包含此修复的当前 `IVORY_REL_5_STABLE` 构建或更新版本的 IvorySQL。
31+
32+
== 安装
33+
34+
先安装 C 编译器、GNU make，以及 MySQL 或 MariaDB 客户端开发包，再显式指定目标 IvorySQL 进行编译：
35+
36+
[source,bash]
37+
----
38+
git clone https://github.com/EnterpriseDB/mysql_fdw.git
39+
cd mysql_fdw
40+
git checkout REL-2_9_3
41+
42+
export PG_CONFIG=/usr/local/ivorysql/bin/pg_config
43+
make USE_PGXS=1 PG_CONFIG="$PG_CONFIG"
44+
sudo make USE_PGXS=1 PG_CONFIG="$PG_CONFIG" install
45+
----
46+
47+
编译前用 `pg_config --version` 确认它指向 IvorySQL。该扩展不需要预加载或重启数据库。
48+
49+
== 准备 MySQL
50+
51+
[source,sql]
52+
----
53+
CREATE DATABASE fdw_test CHARACTER SET utf8mb4;
54+
CREATE USER 'fdw_user'@'%' IDENTIFIED BY 'fdw_pass';
55+
GRANT ALL PRIVILEGES ON fdw_test.* TO 'fdw_user'@'%';
56+
57+
CREATE TABLE fdw_test.products (
58+
id integer PRIMARY KEY,
59+
name varchar(100),
60+
price decimal(10,2),
61+
note varchar(100)
62+
);
63+
INSERT INTO fdw_test.products VALUES
64+
(1, 'IvorySQL', 99.50, '中文'),
65+
(2, 'MySQL', 49.00, NULL);
66+
----
67+
68+
== 配置和使用
69+
70+
[source,sql]
71+
----
72+
CREATE EXTENSION mysql_fdw;
73+
74+
CREATE SERVER mysql_server
75+
FOREIGN DATA WRAPPER mysql_fdw
76+
OPTIONS (host '127.0.0.1', port '3306', character_set 'utf8mb4');
77+
78+
CREATE USER MAPPING FOR CURRENT_USER
79+
SERVER mysql_server
80+
OPTIONS (username 'fdw_user', password 'fdw_pass');
81+
82+
CREATE SCHEMA mysql_remote;
83+
IMPORT FOREIGN SCHEMA fdw_test
84+
FROM SERVER mysql_server INTO mysql_remote;
85+
86+
SELECT * FROM mysql_remote.products ORDER BY id;
87+
INSERT INTO mysql_remote.products VALUES (3, 'FDW', 10.00, 'insert');
88+
UPDATE mysql_remote.products SET price = 11.00 WHERE id = 3;
89+
DELETE FROM mysql_remote.products WHERE id = 3;
90+
----
91+
92+
远端数据库保存 UTF-8 文本时应设置 `character_set 'utf8mb4'`，否则非 ASCII 数据可能被错误解码。
93+
94+
可用 `EXPLAIN VERBOSE` 检查下推，`Remote query` 字段会显示 mysql_fdw 能在远端执行的操作：
95+
96+
[source,sql]
97+
----
98+
EXPLAIN (VERBOSE, COSTS OFF)
99+
SELECT name, price
100+
FROM mysql_remote.products
101+
WHERE price > 40
102+
ORDER BY price DESC
103+
LIMIT 1;
104+
----
105+
106+
== 双模式验证
107+
108+
同一组外表可在 IvorySQL 两种模式中使用：
109+
110+
[source,sql]
111+
----
112+
SET ivorysql.compatible_mode = pg;
113+
SELECT * FROM mysql_remote.products ORDER BY id;
114+
115+
SET ivorysql.compatible_mode = oracle;
116+
SELECT 1 FROM dual;
117+
SELECT * FROM mysql_remote.products ORDER BY id;
118+
INSERT INTO mysql_remote.products VALUES (4, 'Oracle mode', 20.00, NULL);
119+
UPDATE mysql_remote.products SET price = 21.00 WHERE id = 4;
120+
DELETE FROM mysql_remote.products WHERE id = 4;
121+
----
122+
123+
验证覆盖扩展创建、导入模式、UTF-8 和 NULL 值、增删改查，以及两种模式下的过滤、投影、排序和 LIMIT 下推。mysql_fdw 的九组上游回归测试也全部通过：`server_options`、`connection_validation`、`dml`、`select`、`pushdown`、`join_pushdown`、`aggregate_pushdown`、`limit_offset_pushdown` 和 `misc`。
124+
125+
== 故障排查
126+
127+
* `too few arguments to function 'ExecTypeFromTL'`：IvorySQL 安装版本早于上述扩展 API 兼容性修复。
128+
* `Can't connect to MySQL server`：检查主机、端口、防火墙，以及 MySQL 账户是否允许 IvorySQL 所在主机连接。
129+
* 文本乱码：设置服务端选项 `character_set 'utf8mb4'`，并检查远端数据库字符集。
130+
* 生产环境不要在共享脚本中保存密码，并限制用户映射的访问权限。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
*** xref:master/ecosystem_components/zhparser_en.adoc[zhparser]
7777
*** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
7878
*** xref:master/ecosystem_components/set_user.adoc[set_user]
79+
*** xref:master/ecosystem_components/mysql_fdw.adoc[mysql_fdw]
7980
* Monitor and O&M
8081
** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
8182
** xref:master/getting-started/daily_maintenance.adoc[Maintenance]

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
4242
|*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
4343
|*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
4444
| *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
45+
| *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
4546
|====
4647

4748
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‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= mysql_fdw
5+
6+
== Overview
7+
8+
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.
9+
10+
Project page: <https://github.com/EnterpriseDB/mysql_fdw>
11+
12+
Tested version: 2.9.3
13+
14+
License: PostgreSQL License
15+
16+
== Compatibility
17+
18+
The following combination was validated on x86_64 Linux:
19+
20+
[cols="1,1"]
21+
|===
22+
| Component | Version
23+
| IvorySQL | current `IVORY_REL_5_STABLE` (IvorySQL 5.6 / PostgreSQL 18.6)
24+
| mysql_fdw | 2.9.3
25+
| MySQL Server | 8.4
26+
| MariaDB Connector/C | 3.1
27+
|===
28+
29+
[IMPORTANT]
30+
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.
31+
32+
== Installation
33+
34+
Install a C compiler, GNU make, and the MySQL or MariaDB client development package. Then build against the intended IvorySQL installation explicitly:
35+
36+
[source,bash]
37+
----
38+
git clone https://github.com/EnterpriseDB/mysql_fdw.git
39+
cd mysql_fdw
40+
git checkout REL-2_9_3
41+
42+
export PG_CONFIG=/usr/local/ivorysql/bin/pg_config
43+
make USE_PGXS=1 PG_CONFIG="$PG_CONFIG"
44+
sudo make USE_PGXS=1 PG_CONFIG="$PG_CONFIG" install
45+
----
46+
47+
Confirm that `pg_config --version` points to IvorySQL before building. No server preload or restart is required.
48+
49+
== MySQL Preparation
50+
51+
[source,sql]
52+
----
53+
CREATE DATABASE fdw_test CHARACTER SET utf8mb4;
54+
CREATE USER 'fdw_user'@'%' IDENTIFIED BY 'fdw_pass';
55+
GRANT ALL PRIVILEGES ON fdw_test.* TO 'fdw_user'@'%';
56+
57+
CREATE TABLE fdw_test.products (
58+
id integer PRIMARY KEY,
59+
name varchar(100),
60+
price decimal(10,2),
61+
note varchar(100)
62+
);
63+
INSERT INTO fdw_test.products VALUES
64+
(1, 'IvorySQL', 99.50, '中文'),
65+
(2, 'MySQL', 49.00, NULL);
66+
----
67+
68+
== IvorySQL Configuration and Use
69+
70+
[source,sql]
71+
----
72+
CREATE EXTENSION mysql_fdw;
73+
74+
CREATE SERVER mysql_server
75+
FOREIGN DATA WRAPPER mysql_fdw
76+
OPTIONS (host '127.0.0.1', port '3306', character_set 'utf8mb4');
77+
78+
CREATE USER MAPPING FOR CURRENT_USER
79+
SERVER mysql_server
80+
OPTIONS (username 'fdw_user', password 'fdw_pass');
81+
82+
CREATE SCHEMA mysql_remote;
83+
IMPORT FOREIGN SCHEMA fdw_test
84+
FROM SERVER mysql_server INTO mysql_remote;
85+
86+
SELECT * FROM mysql_remote.products ORDER BY id;
87+
INSERT INTO mysql_remote.products VALUES (3, 'FDW', 10.00, 'insert');
88+
UPDATE mysql_remote.products SET price = 11.00 WHERE id = 3;
89+
DELETE FROM mysql_remote.products WHERE id = 3;
90+
----
91+
92+
Set `character_set 'utf8mb4'` when the remote database stores UTF-8 text; otherwise non-ASCII data can be decoded incorrectly.
93+
94+
Use `EXPLAIN VERBOSE` to inspect pushdown. The `Remote query` field should contain operations that mysql_fdw can execute remotely:
95+
96+
[source,sql]
97+
----
98+
EXPLAIN (VERBOSE, COSTS OFF)
99+
SELECT name, price
100+
FROM mysql_remote.products
101+
WHERE price > 40
102+
ORDER BY price DESC
103+
LIMIT 1;
104+
----
105+
106+
== Dual-mode Validation
107+
108+
The same foreign tables can be used in both IvorySQL modes:
109+
110+
[source,sql]
111+
----
112+
SET ivorysql.compatible_mode = pg;
113+
SELECT * FROM mysql_remote.products ORDER BY id;
114+
115+
SET ivorysql.compatible_mode = oracle;
116+
SELECT 1 FROM dual;
117+
SELECT * FROM mysql_remote.products ORDER BY id;
118+
INSERT INTO mysql_remote.products VALUES (4, 'Oracle mode', 20.00, NULL);
119+
UPDATE mysql_remote.products SET price = 21.00 WHERE id = 4;
120+
DELETE FROM mysql_remote.products WHERE id = 4;
121+
----
122+
123+
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`.
124+
125+
== Troubleshooting
126+
127+
* `too few arguments to function 'ExecTypeFromTL'`: the IvorySQL installation is older than the extension-API compatibility fix described above.
128+
* `Can't connect to MySQL server`: verify the host, port, firewall, and that the MySQL account accepts connections from the IvorySQL host.
129+
* Garbled text: set the server option `character_set 'utf8mb4'` and verify the remote database character set.
130+
* Keep credentials out of shared scripts and restrict access to user mappings in production.

0 commit comments

Comments
 (0)