Skip to content

Commit bc822e4

Browse files
messere1messere1
committed
docs: add dblink adaptation guide
1 parent ae32340 commit bc822e4

6 files changed

Lines changed: 227 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/dblink.adoc[dblink]
7980
* 监控运维
8081
** xref:master/getting-started/daily_monitoring.adoc[日常监控]
8182
** xref:master/getting-started/daily_maintenance.adoc[日常维护]

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= dblink
5+
6+
== 概述
7+
8+
`dblink` 可从当前数据库向另一个 IvorySQL 或 PostgreSQL 数据库执行 SQL，支持一次性查询、可复用的命名连接、远程事务、非查询命令和异步查询。
9+
10+
本文使用 IvorySQL 5.6（PostgreSQL 18.6）完成验证：自带 PostgreSQL 回归测试通过，并实际覆盖了命名连接、DML、事务、异步结果、UTF-8 数据和 Oracle 兼容模式会话。
11+
12+
== 编译安装
13+
14+
`dblink` 位于 IvorySQL 源码树中，二进制发行版通常已包含它。如当前安装中缺失，请从匹配的 IvorySQL 5 源码编译：
15+
16+
[source,bash]
17+
----
18+
git clone https://github.com/IvorySQL/IvorySQL.git
19+
cd IvorySQL
20+
git checkout IVORY_REL_5_STABLE
21+
cd contrib/dblink
22+
make USE_PGXS=1 PG_CONFIG=/path-to/ivorysql/bin/pg_config
23+
sudo make USE_PGXS=1 PG_CONFIG=/path-to/ivorysql/bin/pg_config install
24+
----
25+
26+
在每个需要调用 `dblink` 的本地数据库中创建扩展：
27+
28+
[source,sql]
29+
----
30+
CREATE EXTENSION dblink;
31+
----
32+
33+
== 查询远程数据库
34+
35+
先在远程数据库创建测试数据：
36+
37+
[source,sql]
38+
----
39+
CREATE TABLE remote_measurement (
40+
id integer PRIMARY KEY,
41+
label text NOT NULL,
42+
reading numeric NOT NULL
43+
);
44+
INSERT INTO remote_measurement VALUES (1, '北京', 21.5), (2, 'Shanghai', 24.0);
45+
----
46+
47+
建立命名连接，并显式声明返回列类型：
48+
49+
[source,sql]
50+
----
51+
SELECT dblink_connect(
52+
'analytics',
53+
'host=127.0.0.1 port=5432 dbname=remote_db user=ivorysql'
54+
);
55+
56+
SELECT *
57+
FROM dblink('analytics',
58+
'SELECT id, label, reading FROM remote_measurement ORDER BY id')
59+
AS t(id integer, label text, reading numeric);
60+
----
61+
62+
使用 `dblink_exec` 执行不返回行的命令：
63+
64+
[source,sql]
65+
----
66+
SELECT dblink_exec('analytics',
67+
$$UPDATE remote_measurement SET reading = 22.0 WHERE id = 1$$);
68+
----
69+
70+
== 远程事务与异步查询
71+
72+
[source,sql]
73+
----
74+
SELECT dblink_exec('analytics', 'BEGIN');
75+
SELECT dblink_exec('analytics',
76+
$$INSERT INTO remote_measurement VALUES (3, 'temporary', 0)$$);
77+
SELECT dblink_exec('analytics', 'ROLLBACK');
78+
79+
SELECT dblink_send_query('analytics',
80+
'SELECT id, label FROM remote_measurement ORDER BY id');
81+
SELECT * FROM dblink_get_result('analytics') AS t(id integer, label text);
82+
-- 复用连接前，继续调用一次以取尽最后的空结果。
83+
SELECT * FROM dblink_get_result('analytics') AS t(id integer, label text);
84+
85+
SELECT dblink_disconnect('analytics');
86+
----
87+
88+
== Oracle 兼容模式
89+
90+
即使本地会话使用 Oracle 兼容语法，`dblink` 仍通过 PostgreSQL/libpq 协议连接。以下语句已通过 IvorySQL Oracle 兼容端口验证：
91+
92+
[source,sql]
93+
----
94+
SET ivorysql.compatible_mode = oracle;
95+
SELECT 1 FROM dual;
96+
97+
SELECT *
98+
FROM dblink('host=127.0.0.1 port=5432 dbname=remote_db user=ivorysql',
99+
'SELECT id, label FROM remote_measurement ORDER BY id')
100+
AS t(id integer, label text);
101+
----
102+
103+
== 安全与运维说明
104+
105+
* 避免在 SQL 中直接写密码。优先使用 service 文件、权限受限的 `.pgpass`、证书认证或其他服务端凭据机制。
106+
* 只向可信角色授予 `dblink` 权限；远程 SQL 使用远程连接角色的权限执行。
107+
* 对返回行的调用始终显式声明列定义。
108+
* 固定远程 `search_path`、使用带 schema 的对象名，并在不可信网络上启用 TLS。
109+
* 命名连接只属于当前会话。用 `dblink_disconnect` 关闭连接，并在发送下一条命令前取尽异步结果。
110+
111+
完整函数说明请参阅 https://www.postgresql.org/docs/current/dblink.html[PostgreSQL dblink 文档]。

‎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/dblink.adoc[dblink] | IvorySQL 5.6 | 在另一个 IvorySQL 或 PostgreSQL 数据库中执行查询和命令 | 跨库查询、数据交换、管理自动化
4445
|====
4546

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

‎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/dblink.adoc[dblink]
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/dblink.adoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= dblink
5+
6+
== Overview
7+
8+
`dblink` executes SQL in another IvorySQL or PostgreSQL database from the current database. It supports one-shot queries, reusable named connections, remote transactions, non-query commands, and asynchronous queries.
9+
10+
This guide was validated with IvorySQL 5.6 (PostgreSQL 18.6). The bundled PostgreSQL regression suite passed, and named connections, DML, transactions, asynchronous results, UTF-8 data, and Oracle-compatible sessions were tested end to end.
11+
12+
== Build and install
13+
14+
`dblink` is included in the IvorySQL source tree and binary distributions normally install it. If it is absent, build it from the matching IvorySQL 5 source tree:
15+
16+
[source,bash]
17+
----
18+
git clone https://github.com/IvorySQL/IvorySQL.git
19+
cd IvorySQL
20+
git checkout IVORY_REL_5_STABLE
21+
cd contrib/dblink
22+
make USE_PGXS=1 PG_CONFIG=/path-to/ivorysql/bin/pg_config
23+
sudo make USE_PGXS=1 PG_CONFIG=/path-to/ivorysql/bin/pg_config install
24+
----
25+
26+
Create the extension in each local database that will call `dblink`:
27+
28+
[source,sql]
29+
----
30+
CREATE EXTENSION dblink;
31+
----
32+
33+
== Query a remote database
34+
35+
Create sample data in the remote database:
36+
37+
[source,sql]
38+
----
39+
CREATE TABLE remote_measurement (
40+
id integer PRIMARY KEY,
41+
label text NOT NULL,
42+
reading numeric NOT NULL
43+
);
44+
INSERT INTO remote_measurement VALUES (1, '北京', 21.5), (2, 'Shanghai', 24.0);
45+
----
46+
47+
Connect and declare the returned column types explicitly:
48+
49+
[source,sql]
50+
----
51+
SELECT dblink_connect(
52+
'analytics',
53+
'host=127.0.0.1 port=5432 dbname=remote_db user=ivorysql'
54+
);
55+
56+
SELECT *
57+
FROM dblink('analytics',
58+
'SELECT id, label, reading FROM remote_measurement ORDER BY id')
59+
AS t(id integer, label text, reading numeric);
60+
----
61+
62+
Use `dblink_exec` for commands that do not return rows:
63+
64+
[source,sql]
65+
----
66+
SELECT dblink_exec('analytics',
67+
$$UPDATE remote_measurement SET reading = 22.0 WHERE id = 1$$);
68+
----
69+
70+
== Remote transactions and asynchronous queries
71+
72+
[source,sql]
73+
----
74+
SELECT dblink_exec('analytics', 'BEGIN');
75+
SELECT dblink_exec('analytics',
76+
$$INSERT INTO remote_measurement VALUES (3, 'temporary', 0)$$);
77+
SELECT dblink_exec('analytics', 'ROLLBACK');
78+
79+
SELECT dblink_send_query('analytics',
80+
'SELECT id, label FROM remote_measurement ORDER BY id');
81+
SELECT * FROM dblink_get_result('analytics') AS t(id integer, label text);
82+
-- Drain the final empty result before reusing the connection.
83+
SELECT * FROM dblink_get_result('analytics') AS t(id integer, label text);
84+
85+
SELECT dblink_disconnect('analytics');
86+
----
87+
88+
== Oracle-compatible mode
89+
90+
`dblink` uses PostgreSQL/libpq connections, including when the local session uses Oracle-compatible syntax. The following was validated through the IvorySQL Oracle-compatible port:
91+
92+
[source,sql]
93+
----
94+
SET ivorysql.compatible_mode = oracle;
95+
SELECT 1 FROM dual;
96+
97+
SELECT *
98+
FROM dblink('host=127.0.0.1 port=5432 dbname=remote_db user=ivorysql',
99+
'SELECT id, label FROM remote_measurement ORDER BY id')
100+
AS t(id integer, label text);
101+
----
102+
103+
== Security and operational notes
104+
105+
* Avoid embedding passwords in SQL. Prefer a service file, `.pgpass` with restrictive permissions, certificate authentication, or another server-side credential mechanism.
106+
* Grant `dblink` access only to trusted roles. Remote SQL runs with the privileges of the remote connection.
107+
* Always provide an explicit column definition for row-returning calls.
108+
* Fix the remote `search_path`, schema-qualify objects, and use TLS for untrusted networks.
109+
* A named connection is session-local. Close it with `dblink_disconnect`, and fully consume asynchronous results before sending another command.
110+
111+
See https://www.postgresql.org/docs/current/dblink.html[the upstream dblink documentation] for the complete function reference.

‎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/dblink.adoc[dblink] | IvorySQL 5.6 | Executes queries and commands in another IvorySQL or PostgreSQL database | Cross-database queries, data exchange, administrative automation
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.

0 commit comments

Comments
 (0)