From 95c5a8a190b0f25f28806b03d6ea913532ed2872 Mon Sep 17 00:00:00 2001 From: messere1 Date: Sun, 6 Sep 2026 19:20:02 +0800 Subject: [PATCH] docs: add DBeaver adaptation guide --- CN/modules/ROOT/nav.adoc | 1 + .../master/ecosystem_components/dbeaver.adoc | 110 ++++++++++++++++++ .../ecosystem_overview.adoc | 1 + EN/modules/ROOT/nav.adoc | 1 + .../master/ecosystem_components/dbeaver.adoc | 110 ++++++++++++++++++ .../ecosystem_overview.adoc | 1 + 6 files changed, 224 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc create mode 100644 EN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 68f93003..b04da14c 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/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/dbeaver.adoc[DBeaver] * 监控运维 ** xref:master/getting-started/daily_monitoring.adoc[日常监控] ** xref:master/getting-started/daily_maintenance.adoc[日常维护] diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc new file mode 100644 index 00000000..280b50e6 --- /dev/null +++ b/CN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc @@ -0,0 +1,110 @@ +:sectnums: +:sectnumlevels: 5 + += DBeaver + +== 概述 + +DBeaver Community 是跨平台图形化数据库客户端。IvorySQL 使用 PostgreSQL 传输协议，因此无需安装 IvorySQL 专用插件，使用 DBeaver 的 PostgreSQL 驱动即可连接。 + +本文在 Windows 11 上使用 DBeaver Community 26.2.0、PostgreSQL JDBC 42.7.13 和 IvorySQL 5.4（PostgreSQL 18.4）完成验证。通过 PostgreSQL 兼容端口实际测试了 Database Navigator 元数据会话、SQL 编辑器、DDL、DML、UTF-8 数据、事务回滚和执行计划；通过 Oracle 兼容端口测试了 Oracle 数据类型 DDL/DML、`dual` 和事务回滚。 + +== 创建 PostgreSQL 兼容连接 + +. 在 DBeaver 中选择 *数据库* > *新建数据库连接*。 +. 选择 *PostgreSQL* 数据库驱动。 +. 填写连接参数： + +[cols="1,2"] +|==== +|设置 |值 + +|主机 +|IvorySQL 服务器地址，例如 `127.0.0.1` + +|端口 +|PostgreSQL 兼容端口，默认为 `5432` + +|数据库 +|目标数据库，例如 `ivorysql` + +|用户名 +|IvorySQL 登录角色 + +|密码 +|角色密码 +|==== + +. 如有提示，允许 DBeaver 下载 PostgreSQL JDBC 驱动。 +. 单击 *测试连接*，成功后单击 *完成*。 + +对应的 JDBC URL 为： + +[source,text] +---- +jdbc:postgresql://127.0.0.1:5432/ivorysql +---- + +== 验证连接 + +打开该连接的 SQL 编辑器并执行： + +[source,sql] +---- +SELECT version(); + +CREATE TABLE dbeaver_validation ( + id integer PRIMARY KEY, + label text NOT NULL +); +INSERT INTO dbeaver_validation VALUES (1, 'IvorySQL'), (2, '北京'); +SELECT * FROM dbeaver_validation ORDER BY id; + +EXPLAIN SELECT * FROM dbeaver_validation WHERE id = 1; +---- + +在 Database Navigator 中刷新 `public` schema，应能看到该表及其两列。使用 *数据* > *查看数据* 可浏览或编辑数据行。 + +如需验证事务控制，可关闭自动提交、插入一行后单击 *回滚*，并确认该行不存在。 + +== 连接 Oracle 兼容端口 + +使用相同的 PostgreSQL 驱动和数据库参数创建第二个连接，但将端口改为 IvorySQL Oracle 兼容端口（默认为 `1521`）。该连接仍使用 PostgreSQL JDBC 协议，不同端口用于选择 IvorySQL Oracle 兼容 SQL 模式。 + +[source,text] +---- +jdbc:postgresql://127.0.0.1:1521/ivorysql +---- + +在 SQL 编辑器中验证 Oracle 兼容语法： + +[source,sql] +---- +SELECT 1 FROM dual; + +CREATE TABLE dbeaver_ora_validation ( + id NUMBER PRIMARY KEY, + label VARCHAR2(40) +); +INSERT INTO dbeaver_ora_validation VALUES (1, 'IvorySQL'); +SELECT * FROM dbeaver_ora_validation; +DROP TABLE dbeaver_ora_validation; +---- + +也可以使用 PostgreSQL 兼容连接，只切换当前会话： + +[source,sql] +---- +SET ivorysql.compatible_mode=oracle; +SELECT 1 FROM dual; +---- + +== 注意事项与限制 + +* DBeaver 会将 IvorySQL 识别为 PostgreSQL，可使用 PostgreSQL 导航、元数据、数据编辑和执行计划功能，但不提供面向 Oracle 数据库的专用管理面板。 +* `SET ivorysql.compatible_mode` 只影响当前数据库会话。DBeaver 会建立额外的元数据和编辑器会话，因此使用独立的 Oracle 端口连接可避免各会话模式不一致。 +* 使用带双引号的 Oracle 兼容标识符时应保留大小写；两种兼容模式对未加引号标识符的大小写折叠规则不同。 +* 不要在共享工作站保存生产密码；应使用 TLS 和部署环境要求的认证方式。 +* 对生产连接可启用 DBeaver 的只读和 SQL 执行限制，降低误操作风险。 + +SSL、SSH、代理及高级驱动设置请参阅 https://dbeaver.com/docs/dbeaver/Database-driver-PostgreSQL/[DBeaver PostgreSQL 驱动文档]。 diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc index 074ce67c..d0728148 100644 --- a/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc +++ b/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/dbeaver.adoc[DBeaver] | 26.2.0 | 提供图形化数据库导航、SQL 编辑、数据编辑和执行计划 | 数据库开发与管理 |==== 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 1103c116..bf9c8645 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/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/dbeaver.adoc[DBeaver] * Monitor and O&M ** xref:master/getting-started/daily_monitoring.adoc[Monitoring] ** xref:master/getting-started/daily_maintenance.adoc[Maintenance] diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc new file mode 100644 index 00000000..5aa5ba6d --- /dev/null +++ b/EN/modules/ROOT/pages/master/ecosystem_components/dbeaver.adoc @@ -0,0 +1,110 @@ +:sectnums: +:sectnumlevels: 5 + += DBeaver + +== Overview + +DBeaver Community is a cross-platform graphical database client. IvorySQL uses the PostgreSQL wire protocol, so DBeaver can connect with its PostgreSQL driver without an IvorySQL-specific plugin. + +This guide was validated on Windows 11 with DBeaver Community 26.2.0, PostgreSQL JDBC 42.7.13, and IvorySQL 5.4 (PostgreSQL 18.4). Database Navigator metadata sessions, the SQL editor, DDL, DML, UTF-8 data, transaction rollback, and execution plans were tested through the PostgreSQL-compatible port. Oracle-compatible DDL, DML, `dual`, and transaction rollback were also tested through the Oracle-compatible port. + +== Create a PostgreSQL-compatible connection + +. In DBeaver, select *Database* > *New Database Connection*. +. Select *PostgreSQL* as the database driver. +. Enter the connection settings: + +[cols="1,2"] +|==== +|Setting |Value + +|Host +|IvorySQL server address, for example `127.0.0.1` + +|Port +|The PostgreSQL-compatible port, `5432` by default + +|Database +|Target database, for example `ivorysql` + +|Username +|An IvorySQL login role + +|Password +|The role password +|==== + +. If prompted, allow DBeaver to download the PostgreSQL JDBC driver. +. Select *Test Connection*, then *Finish*. + +The equivalent JDBC URL is: + +[source,text] +---- +jdbc:postgresql://127.0.0.1:5432/ivorysql +---- + +== Validate the connection + +Open an SQL editor for the connection and run: + +[source,sql] +---- +SELECT version(); + +CREATE TABLE dbeaver_validation ( + id integer PRIMARY KEY, + label text NOT NULL +); +INSERT INTO dbeaver_validation VALUES (1, 'IvorySQL'), (2, '北京'); +SELECT * FROM dbeaver_validation ORDER BY id; + +EXPLAIN SELECT * FROM dbeaver_validation WHERE id = 1; +---- + +Refresh the `public` schema in Database Navigator. The table and its two columns should appear. Use *Data* > *View Data* to inspect or edit rows. + +To verify transaction control, disable auto-commit, insert a row, select *Rollback*, and confirm that the row is absent. + +== Connect to the Oracle-compatible port + +Create a second connection with the same PostgreSQL driver and database settings, but use the IvorySQL Oracle-compatible port (`1521` by default). This remains a PostgreSQL JDBC connection; the different port selects IvorySQL's Oracle-compatible SQL mode. + +[source,text] +---- +jdbc:postgresql://127.0.0.1:1521/ivorysql +---- + +Validate Oracle-compatible syntax in the SQL editor: + +[source,sql] +---- +SELECT 1 FROM dual; + +CREATE TABLE dbeaver_ora_validation ( + id NUMBER PRIMARY KEY, + label VARCHAR2(40) +); +INSERT INTO dbeaver_ora_validation VALUES (1, 'IvorySQL'); +SELECT * FROM dbeaver_ora_validation; +DROP TABLE dbeaver_ora_validation; +---- + +Alternatively, use the PostgreSQL-compatible connection and switch only the current session: + +[source,sql] +---- +SET ivorysql.compatible_mode=oracle; +SELECT 1 FROM dual; +---- + +== Notes and limitations + +* DBeaver identifies IvorySQL as PostgreSQL. PostgreSQL navigation, metadata, editing, and plan features are available; Oracle-specific DBeaver administration panels are not expected. +* A `SET ivorysql.compatible_mode` command applies only to its current database session. A dedicated Oracle-port connection avoids mode changes when DBeaver opens additional metadata or editor sessions. +* Preserve the case of quoted Oracle-compatible identifiers. Unquoted identifier folding differs between compatibility modes. +* Do not save production passwords on shared workstations. Prefer TLS and the authentication method required by your deployment. +* For production connections, consider enabling DBeaver's read-only and SQL execution restrictions to reduce accidental changes. + +See the https://dbeaver.com/docs/dbeaver/Database-driver-PostgreSQL/[DBeaver PostgreSQL driver documentation] for advanced SSL, SSH, proxy, and driver settings. diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc index 4e3270c9..b341c476 100644 --- a/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc +++ b/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/dbeaver.adoc[DBeaver] | 26.2.0 | Graphical database navigation, SQL editing, data editing, and execution plans | Database development and administration |==== 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.