diff --git a/docs/connection-integration/data-integration/dbeaver.md b/docs/connection-integration/data-integration/dbeaver.md index 0fb772e9ce325..247c52c0fc8ba 100644 --- a/docs/connection-integration/data-integration/dbeaver.md +++ b/docs/connection-integration/data-integration/dbeaver.md @@ -2,126 +2,270 @@ { "title": "DBeaver", "language": "en", - "description": "Use DBeaver to connect to Apache Doris through the MySQL driver, visually manage internal catalog and external catalog, and run SQL queries." + "description": "Connect DBeaver to Apache Doris with the Apache Doris or MySQL driver, browse internal and external catalogs, and run SQL queries." } --- - + DBeaver is a cross-platform database tool for developers, database administrators, analysts, and anyone who works with data. -Apache Doris is highly compatible with the MySQL protocol, so you can use the MySQL driver in DBeaver to connect to Apache Doris and query data in the internal catalog and external catalog. +Apache Doris accepts queries through the MySQL protocol. DBeaver 26.1.1 and later include an `Apache Doris` data source that you can use to query internal and external catalogs. + +If the `Select your database` window does not list `Apache Doris`, use the MySQL driver instead. See [Connect with the MySQL driver](#connect-with-the-mysql-driver). ## Use cases -- Browse metadata such as databases, tables, and views in Apache Doris through a visual interface. -- Use the SQL editor to run queries and analyze data. -- Manage the internal catalog and multiple external catalogs in a single tool. -- Monitor sessions and view runtime information such as system variables and user privileges. +- Browse Apache Doris catalogs, databases, tables, views, and other metadata. +- Run queries and analyze data in the SQL editor. +- Manage internal and external catalogs in one tool. +- Inspect sessions, system variables, user privileges, and other runtime information. ## Prerequisites -- DBeaver is installed (version 24.0.0 or later is recommended). Download URL: [https://dbeaver.io](https://dbeaver.io) -- An Apache Doris cluster is reachable, and you know the FE host address, query port, username, and password. -- To connect to an external catalog using the `catalog.db` form, the Doris version must be 2.1.0 or later. +- Install DBeaver 26.1.1 or later from [https://dbeaver.io](https://dbeaver.io). +- You can reach the Apache Doris cluster and have the FE host address, MySQL protocol port, username, and password. +- Use Doris 2.1.0 or later to connect to an external catalog with the `catalog.db` format. + +## Connect DBeaver to Doris -## Procedure +### Connect with the Apache Doris driver (recommended) -:::info Note -The following steps are verified on DBeaver 24.0.0. +:::warning Version requirement +DBeaver 26.1.1 or later is required. ::: -### Step 1: Create a new database connection +#### Step 1: Create a database connection -1. Start DBeaver. -2. In the upper-left corner of the window, click the plus (**+**) icon, or select **Database > New Database Connection** from the menu bar to open the **Connect to a database** dialog. +Start DBeaver. - ![Add connection 1](/images/next/connection-integration/data-integration/dbeaver/dbeaver1.png) +Click the plus (`+`) icon in the upper-left corner, or select `Database` > `New Database Connection` from the menu bar. DBeaver opens the `Connect to a database` window. - ![Add connection 2](/images/next/connection-integration/data-integration/dbeaver/dbeaver2.png) +![Create a database connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg) -### Step 2: Select the MySQL driver +#### Step 2: Select the Apache Doris driver -In the **Select your database** window, select **MySQL**. +In the `Select your database` window, search for or select `Apache Doris`, then click `Next`. -![Select driver](/images/next/connection-integration/data-integration/dbeaver/dbeaver3.png) +![Select the Apache Doris driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg) -### Step 3: Configure the Doris connection +#### Step 3: Configure the Doris connection -On the **Main** tab of the **Connection Settings** window, fill in the following connection information: +On the `Main` tab of the `Apache Doris connection settings` window, enter the following values: | Field | Description | Example | -|--------|------|------| -| Server Host | The FE host IP address of the Doris cluster | `127.0.0.1` | -| Port | The FE query port of the Doris cluster | `9030` | -| Database | The target database in the Doris cluster | `example_db` or `hive.example_db` | -| Username | The username used to log in to the Doris cluster | `admin` | -| Password | The password used to log in to the Doris cluster | - | +|-------|-------------|---------| +| Host | FE host name or IP address. If you use an SSH tunnel, enter the local forwarding address. | `127.0.0.1` | +| Port | FE MySQL protocol port. If you use an SSH tunnel, enter the local forwarding port. | `9030` or `19030` | +| Database/Schema | Optional. The target database. To connect directly to an external catalog, use the `catalog.db` format. | `example_db` or `hive.example_db` | +| Username | Username for the Doris cluster. | `admin` | +| Password | Password for the Doris cluster. | - | -:::tip How to use the Database field -The Database field can be used to distinguish between the internal catalog and external catalogs: +The `Database/Schema` value determines which catalog and database DBeaver opens: -- Database name only: by default, the data source connects to the internal catalog. -- The format `catalog.db`: the data source connects to the specified catalog by default, and the databases and tables shown in DBeaver are those in that catalog. +- Leave it blank to browse catalogs and databases in the Database Navigator after connecting. +- Enter a database name to open that database in the internal catalog. +- Enter `catalog.db` to open a database in the specified external catalog. DBeaver displays the tables from that catalog and database. -Therefore, you can create multiple Doris data sources to manage different catalogs separately. +:::note +The `catalog.db` format requires Doris 2.1.0 or later. ::: -:::info Note -Connecting to a Doris external catalog with the `catalog.db` form requires Doris version 2.1.0 or later. +Connect to the internal catalog: + +![Connect to the internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg) + +Connect to an external catalog: + +![Connect to an external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg) + +To use DBeaver's built-in SSH support, click `SSH, Proxy` in the upper-right corner and configure the tunnel. If you already created local port forwarding, enter the local address and port in `Host` and `Port`. + +#### Step 4: Test and save the connection + +Click `Test Connection` in the lower-left corner. + +When DBeaver reports a successful connection, click `OK`. + +Click `Finish` to save the connection. + +![Test the Apache Doris driver connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg) + +#### Step 5: Browse Doris objects + +The new data source appears in the Database Navigator. Expand it to browse Doris catalogs, databases, tables, and views. + +![Browse Doris objects](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg) + +#### Configure driver properties + +The Apache Doris driver uses MySQL Connector/J to connect to the FE MySQL protocol port. The default port is `9030`, and the default user is `root`. The JDBC URL template is: + +```text +jdbc:mysql://{host}[:{port}]/[{database}] +``` + +The driver class is: + +```text +com.mysql.cj.jdbc.Driver +``` + +By default, the driver sets: + +```text +connectTimeout=20000 +rewriteBatchedStatements=true +useSSL=false +enabledTLSProtocols=TLSv1.2,TLSv1.3 +``` + +![Configure Apache Doris driver properties](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg) + +`useSSL=false` disables TLS/SSL by default. If the FE MySQL protocol port has TLS enabled and the certificate chain is configured correctly, set the MySQL Connector/J SSL properties under `Driver properties`. For example: + +```text +useSSL=true +sslMode=REQUIRED +``` + +To verify the certificate authority, configure a Java truststore: + +```text +sslMode=VERIFY_CA +trustCertificateKeyStoreUrl=file:/path/to/doris-truststore.jks +trustCertificateKeyStorePassword= +``` + +To also verify the server host name, use: + +```text +sslMode=VERIFY_IDENTITY +``` + +With `VERIFY_IDENTITY`, the `Host` value in DBeaver must match the certificate's SAN or CN. + +### Connect with the MySQL driver + +If the `Select your database` window does not list `Apache Doris`, connect with the MySQL driver. + +#### Step 1: Create a database connection + +Start DBeaver. + +Click the plus (`+`) icon in the upper-left corner, or select `Database` > `New Database Connection` from the menu bar. DBeaver opens the `Connect to a database` window. + +![Create a MySQL database connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg) + +#### Step 2: Select the MySQL driver + +In the `Select your database` window, select `MySQL`. + +#### Step 3: Configure the Doris connection + +On the `Main` tab of the `Connection Settings` window, enter the following values: + +| Field | Description | Example | +|-------|-------------|---------| +| Server Host | FE host name or IP address. | `127.0.0.1` | +| Port | FE MySQL protocol port. | `9030` | +| Database | Target database. To connect directly to an external catalog, use the `catalog.db` format. | `example_db` or `hive.example_db` | +| Username | Username for the Doris cluster. | `admin` | +| Password | Password for the Doris cluster. | - | + +The `Database` value determines the default catalog: + +- Enter a database name to open that database in the internal catalog. +- Enter `catalog.db` to open a database in the specified external catalog. DBeaver displays the tables from that catalog and database. + +Create separate Doris data sources if you need direct access to several catalogs. + +:::note +The `catalog.db` format requires Doris 2.1.0 or later. ::: -Connection examples: +Connect to the internal catalog: + +![Connect to the internal catalog with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg) + +Connect to an external catalog: -- Connect to the internal catalog +![Connect to an external catalog with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg) - ![Connect to internal catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver4.png) +#### Step 4: Test and save the connection -- Connect to an external catalog +Click `Test Connection` in the lower-left corner. - ![Connect to external catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver5.png) +When DBeaver reports a successful connection, click `OK`. -### Step 4: Test and save the connection +![Test the MySQL driver connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg) -1. After filling in the connection information, click **Test Connection** in the lower-left corner to verify that the information is correct. -2. When DBeaver displays a confirmation dialog, click **OK** to confirm that the configuration is correct. -3. Click **Finish** in the lower-right corner to complete the connection setup. +Click `Finish` to save the connection. -![Test connection](/images/next/connection-integration/data-integration/dbeaver/dbeaver6.png) +#### Step 5: Manage the database -### Step 5: Connect to and manage the database +The new data source appears in the Database Navigator. Use it to connect to and manage the database. -After the database connection is established, you can see the new data source in the database connection navigator on the left, and connect to and manage it through DBeaver. +![Manage the database with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg) -![Establish connection](/images/next/connection-integration/data-integration/dbeaver/dbeaver7.png) +## Driver selection and feature support -## Feature support +### Choose a driver -DBeaver supports Apache Doris features as follows: +Both the Apache Doris driver and the MySQL driver connect to Doris through the FE MySQL protocol port. They differ mainly in how DBeaver models metadata, organizes objects in the navigator, and exposes administration features. -### Fully supported +Use the following guidelines to select a driver: -| Category | Feature | -|------|--------| -| Visual viewing | Databases (Tables, Views), Users | -| Administer | Session Manager | -| System Info | Session Variables, Global Variables, Engines, Charsets, User Privileges, Plugin | -| Operations | SQL editor, SQL console | +| Use case | Recommended driver | +|----------|--------------------| +| Connect to Doris, run SQL, and browse databases and tables | Apache Doris driver | +| Browse the internal catalog and multiple external catalogs in one connection | Apache Doris driver | +| The current DBeaver version does not provide an Apache Doris data source | MySQL driver | +| View Users, Session Manager, and System Info | MySQL driver | -### Basically supported +If you only work with the internal catalog, either driver can connect to Doris and execute SQL. However, the Apache Doris driver is recommended. -You can click and view these items without errors, but due to protocol compatibility issues, some content may not be fully displayed: +### Feature comparison + +| Feature | Apache Doris driver | MySQL driver | +|---------|---------------------|--------------| +| Connect to Doris and execute SQL | Supported | Supported | +| Browse the internal catalog | Supported | Supported | +| Browse multiple catalogs in one connection | Supported | Not supported | +| Browse external catalogs in Database Navigator | Supported | Not supported | +| Use `catalog.db` as the default SQL context | Supported | Supported | +| View tables, views, columns, and DDL | Supported | Supported | +| SQL editor and SQL console | Supported | Supported | +| View data through the UI | Supported | Supported | +| Insert data through the UI | Supported | Supported | +| View Users, Session Manager, and System Info | Not supported | Supported | +| Tools > Analyse | Not supported | Supported | +| Tools > Truncate | Not supported | Supported | + +:::note Support scope + +This table defines supported capabilities using an allowlist: + +- Only features explicitly marked as "Supported" in the table are within the scope of this document. +- DBeaver UI operations and administration features not listed in the table are not supported. +- When you use the MySQL driver, the presence of a MySQL feature in the DBeaver interface does not mean that Doris supports it. +- Users, Session Manager, and System Info are read-only. You cannot use DBeaver to modify users, privileges, or sessions. +- Support for `Analyse` and `Truncate` applies only to the DBeaver Tools menu when you use the MySQL driver. With the Apache Doris driver, run the corresponding Doris SQL statements in the SQL editor. + +::: -- Dashboard -- Users / user / properties -- Session Status -- Global Status +### Important limitations -### Not supported +Neither driver supports the following operations: -When using DBeaver to manage Apache Doris, certain visual operations may report errors or have not been verified, for example: +- Update or delete existing data through the UI. +- Create tables through the UI. +- Add or modify columns through the UI. +- Create or modify indexes through the UI. +- Create foreign keys or triggers through the UI. +- Configure key models, partitions, buckets, replica counts, or table properties through the UI. +- Session Status, Global Status, or Dashboard. +- Check, Optimize, Repair, or Dump database. -- Visually creating databases and tables -- Schema Change -- Visually inserting, deleting, or updating data +Use the SQL editor to change Doris table schemas and to update or delete existing data. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/dbeaver.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/dbeaver.md index 6dd3d511d73d0..8e2f0d01dda99 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/dbeaver.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/dbeaver.md @@ -2,7 +2,7 @@ { "title": "DBeaver", "language": "zh-CN", - "description": "使用 DBeaver 通过 MySQL 驱动连接 Apache Doris,可视化管理 internal catalog 与 external catalog,执行 SQL 查询。" + "description": "使用 DBeaver 的 Apache Doris 驱动或 MySQL 驱动连接 Apache Doris,浏览和管理 internal catalog 与 external catalog,并执行 SQL 查询。" } --- @@ -11,117 +11,261 @@ DBeaver 是一款跨平台数据库工具,适用于开发人员、数据库管理员、分析师以及所有处理数据的用户。 -Apache Doris 高度兼容 MySQL 协议,可使用 DBeaver 的 MySQL 驱动连接 Apache Doris,并查询 internal catalog 和 external catalog 中的数据。 +Apache Doris 可通过 MySQL 协议对外提供查询服务。在包含 Apache Doris 驱动的 DBeaver 版本中,可以直接使用 `Apache Doris` 数据源入口连接 Doris,并查询 internal catalog 和 external catalog 中的数据。 + +如果当前 DBeaver 版本中没有 `Apache Doris` 驱动入口,也可以通过 MySQL 驱动连接 Apache Doris。具体操作请参考[使用 MySQL 驱动连接 Doris](#使用-mysql-驱动连接-doris)。 ## 适用场景 -- 通过可视化界面浏览 Apache Doris 的库、表、视图等元数据 -- 使用 SQL 编辑器执行查询、分析数据 -- 在同一工具中统一管理 internal catalog 与多个 external catalog -- 监控会话、查看系统变量与用户权限等运行信息 +- 通过可视化界面浏览 Apache Doris 的 catalog、database、table、view 等元数据。 +- 使用 SQL 编辑器执行查询、分析数据。 +- 在同一工具中管理 internal catalog 与 external catalog。 +- 查看会话、系统变量、用户权限等运行信息。 ## 前置条件 -- 已安装 DBeaver(推荐 24.0.0 及以上版本),下载地址:[https://dbeaver.io](https://dbeaver.io) -- 可访问的 Apache Doris 集群,并已知 FE 主机地址、查询端口、账号与密码 -- 若需通过 `catalog.db` 形式连接 external catalog,Doris 版本需为 2.1.0 及以上 +- 已安装 DBeaver 26.1.1 或更高版本,下载地址:[https://dbeaver.io](https://dbeaver.io)。 +- 可访问 Apache Doris 集群,并已知 FE 主机地址、MySQL 协议端口、账号与密码。 +- 若需通过 `catalog.db` 形式连接 external catalog,Doris 版本需为 2.1.0 及以上。 ## 操作步骤 -:::info 备注 -当前操作基于 DBeaver 24.0.0 版本验证。 +### 使用 Apache Doris 驱动连接 Doris(推荐) + +:::warning 版本要求 +DBeaver 需要升级到 26.1.1 或更高版本。 ::: -### 步骤 1:新建数据库连接 +#### 步骤 1:新建数据库连接 -1. 启动 DBeaver。 -2. 在窗口左上角单击加号(**+**)图标,或在菜单栏选择 **Database > New Database Connection**,打开 **Connect to a database** 界面。 +启动 DBeaver。 - ![添加连接 1](/images/next/connection-integration/data-integration/dbeaver/dbeaver1.png) +在窗口左上角单击加号(`+`)图标,或在菜单栏选择 `Database` > `New Database Connection`,打开 `Connect to a database` 界面。 - ![添加连接 2](/images/next/connection-integration/data-integration/dbeaver/dbeaver2.png) +![新建数据库连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg) -### 步骤 2:选择 MySQL 驱动 +#### 步骤 2:选择 Apache Doris 驱动 -在 **Select your database** 窗口中选择 **MySQL**。 +在 `Select your database` 窗口中搜索或选择 `Apache Doris`,然后单击 `Next`。 -![选择驱动](/images/next/connection-integration/data-integration/dbeaver/dbeaver3.png) +![选择 Apache Doris 驱动](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg) -### 步骤 3:配置 Doris 连接信息 +#### 步骤 3:配置 Doris 连接信息 -在 **Connection Settings** 窗口的 **Main** 标签页填写以下连接信息: +在 `Apache Doris connection settings` 窗口的 `Main` 标签页填写以下连接信息: | 配置项 | 说明 | 示例 | |--------|------|------| -| Server Host | Doris 集群的 FE 主机 IP 地址 | `127.0.0.1` | -| Port | Doris 集群的 FE 查询端口 | `9030` | -| Database | Doris 集群中的目标数据库 | `example_db` 或 `hive.example_db` | -| Username | 用于登录 Doris 集群的用户名 | `admin` | -| Password | 用于登录 Doris 集群的用户密码 | - | +| Host | Doris 集群的 FE 主机地址。如果使用 SSH 隧道,填写本地转发地址。 | `127.0.0.1` | +| Port | Doris 集群的 FE MySQL 协议端口。如果使用 SSH 隧道,填写本地转发端口。 | `9030` 或 `19030` | +| Database/Schema | 可选。Doris 集群中的目标 database,也可使用 `catalog.db` 形式连接 external catalog。 | `example_db` 或 `hive.example_db` | +| Username | 用于登录 Doris 集群的用户名。 | `admin` | +| Password | 用于登录 Doris 集群的用户密码。 | - | -:::tip Database 字段使用说明 -Database 字段可用于区分 internal catalog 与 external catalog: +`Database/Schema` 字段可用于区分 internal catalog 与 external catalog: -- 仅填写 Database 名称:当前数据源默认连接 internal catalog。 -- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog,DBeaver 中展示的库表也为该 catalog 中的库表。 +- 留空:连接建立后在 DBeaver 的 Database Navigator 中浏览 catalog 和 database。 +- 仅填写 database 名称:当前数据源默认连接 internal catalog 下的指定 database。 +- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog 下的指定 database,DBeaver 中展示的库表也为该 catalog 中的库表。 -因此,可通过创建多个 Doris 数据源来分别管理不同的 Catalog。 +:::note 备注 +通过 `catalog.db` 形式连接 Doris 的 external catalog 需要 Doris 版本在 2.1.0 及以上。 ::: -:::info 备注 +连接 internal catalog: + +![连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg) + +连接 external catalog: + +![连接 external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg) + +如需通过 DBeaver 内置 SSH 功能连接,可以单击右上角 `SSH, Proxy` 配置 SSH 隧道。如果已在本机提前建立端口转发,则在 `Host` 和 `Port` 中填写本地转发地址和端口。 + +#### 步骤 4:测试并保存连接 + +填写完连接信息后,单击左下角 `Test Connection` 验证连接信息的准确性。 + +DBeaver 弹出确认对话框后,单击 `OK` 确认配置无误。 + +单击右下角 `Finish` 完成连接配置。 + +![测试 Apache Doris 驱动连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg) + +#### 步骤 5:连接并管理数据库 + +数据库连接建立完成后,可在左侧的数据库连接导航栏看到已创建的数据源,并通过 DBeaver 浏览 Doris catalog、database、table、view 等对象。 + +![浏览 Doris 数据库对象](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg) + +#### 配置 Driver Properties + +Apache Doris 驱动底层使用 MySQL Connector/J 连接 Doris FE 的 MySQL 协议端口。驱动默认端口为 `9030`,默认用户为 `root`,JDBC URL 模板如下: + +```text +jdbc:mysql://{host}[:{port}]/[{database}] +``` + +驱动类为: + +```text +com.mysql.cj.jdbc.Driver +``` + +常见默认参数如下: + +```text +connectTimeout=20000 +rewriteBatchedStatements=true +useSSL=false +enabledTLSProtocols=TLSv1.2,TLSv1.3 +``` + +![配置 Apache Doris 驱动属性](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg) + +`useSSL=false` 表示默认不启用 TLS/SSL。若 Doris FE 的 MySQL 协议端口已正确开启 TLS,并且证书链配置正确,可在 DBeaver 的 `Driver properties` 中配置 MySQL Connector/J 的 SSL 参数,例如: + +```text +useSSL=true +sslMode=REQUIRED +``` + +如需校验证书,可配置 Java truststore,并使用: + +```text +sslMode=VERIFY_CA +trustCertificateKeyStoreUrl=file:/path/to/doris-truststore.jks +trustCertificateKeyStorePassword= +``` + +如需同时校验服务端主机名,可使用: + +```text +sslMode=VERIFY_IDENTITY +``` + +使用 `VERIFY_IDENTITY` 时,DBeaver 中填写的 Host 必须和服务端证书的 SAN/CN 匹配。 + +### 使用 MySQL 驱动连接 Doris + +如果当前 DBeaver 版本中没有 `Apache Doris` 驱动入口,可以通过 MySQL 驱动连接 Apache Doris。 + +#### 步骤 1:新建数据库连接 + +启动 DBeaver。 + +在窗口左上角单击加号(`+`)图标,或在菜单栏选择 `Database` > `New Database Connection`,打开 `Connect to a database` 界面。 + +![新建 MySQL 数据库连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg) + +#### 步骤 2:选择 MySQL 驱动 + +在 `Select your database` 窗口中选择 `MySQL`。 + +#### 步骤 3:配置 Doris 连接信息 + +在 `Connection Settings` 窗口的 `Main` 标签页填写以下连接信息: + +| 配置项 | 说明 | 示例 | +|--------|------|------| +| Server Host | Doris 集群的 FE 主机 IP 地址。 | `127.0.0.1` | +| Port | Doris 集群的 FE MySQL 协议端口。 | `9030` | +| Database | Doris 集群中的目标 database,也可使用 `catalog.db` 形式连接 external catalog。 | `example_db` 或 `hive.example_db` | +| Username | 用于登录 Doris 集群的用户名。 | `admin` | +| Password | 用于登录 Doris 集群的用户密码。 | - | + +`Database` 字段可用于区分 internal catalog 与 external catalog: + +- 仅填写 database 名称:当前数据源默认连接 internal catalog。 +- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog,DBeaver 中展示的库表也为该 catalog 中的库表。 + +因此,可通过创建多个 Doris 数据源来分别管理不同的 catalog。 + +:::note 备注 通过 `catalog.db` 形式连接 Doris 的 external catalog 需要 Doris 版本在 2.1.0 及以上。 ::: -连接示例: +连接 internal catalog: + +![通过 MySQL 驱动连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg) -- 连接 internal catalog +连接 external catalog: - ![连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver4.png) +![通过 MySQL 驱动连接 external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg) -- 连接 external catalog +#### 步骤 4:测试并保存连接 - ![连接 external catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver5.png) +填写完连接信息后,单击左下角 `Test Connection` 验证连接信息的准确性。 -### 步骤 4:测试并保存连接 +DBeaver 弹出确认对话框后,单击 `OK` 确认配置无误。 -1. 填写完连接信息后,单击左下角 **Test Connection** 验证连接信息的准确性。 -2. DBeaver 弹出确认对话框后,单击 **OK** 确认配置无误。 -3. 单击右下角 **Finish** 完成连接配置。 +![测试 MySQL 驱动连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg) -![测试连接](/images/next/connection-integration/data-integration/dbeaver/dbeaver6.png) +单击右下角 `Finish` 完成连接配置。 -### 步骤 5:连接并管理数据库 +#### 步骤 5:连接并管理数据库 数据库连接建立完成后,可在左侧的数据库连接导航栏看到已创建的数据源,并通过 DBeaver 进行连接与管理。 -![建立连接](/images/next/connection-integration/data-integration/dbeaver/dbeaver7.png) +![通过 MySQL 驱动管理数据库](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg) -## 功能支持 +## 驱动选择与功能支持 -DBeaver 对 Apache Doris 的功能支持情况如下: +### 如何选择驱动 -### 完全支持 +Apache Doris 驱动和 MySQL 驱动均通过 Doris FE 的 MySQL 协议端口连接 Doris。两个驱动的主要区别在于 DBeaver 的元数据模型、对象导航结构和管理功能入口。 -| 类别 | 功能项 | -|------|--------| -| 可视化查看 | Databases(Tables、Views)、Users | -| Administer | Session Manager | -| System Info | Session Variables、Global Variables、Engines、Charsets、User Privileges、Plugin | -| 操作类 | SQL 编辑器、SQL 控制台 | +推荐按以下原则选择驱动: -### 基本支持 +| 使用需求 | 推荐选择 | +|----------|----------| +| 日常连接 Doris、执行 SQL、浏览库表 | Apache Doris 驱动 | +| 在同一连接中浏览 internal catalog 和多个 external catalog | Apache Doris 驱动 | +| 当前 DBeaver 中没有 Apache Doris 数据源入口 | MySQL 驱动 | +| 查看 Users、Session Manager 和 System Info | MySQL 驱动 | -可点击查看且不会报错,但由于协议兼容问题,可能存在显示不全的情况: +如果只操作 internal catalog,两个驱动均可用于连接和执行 SQL,但推荐优先使用 Apache Doris 驱动。 + +### 功能对比 + +| 功能 | Apache Doris 驱动 | MySQL 驱动 | +|------|-------------------|------------| +| 连接 Doris、执行 SQL | 支持 | 支持 | +| 浏览 internal catalog | 支持 | 支持 | +| 在同一连接中浏览多个 catalog | 支持 | 不支持 | +| 在 Database Navigator 中浏览 external catalog | 支持 | 不支持 | +| 使用 `catalog.db` 作为 SQL 默认上下文 | 支持 | 支持 | +| 查看表、视图、字段和 DDL | 支持 | 支持 | +| SQL 编辑器、SQL 控制台 | 支持 | 支持 | +| 可视化查看数据 | 支持 | 支持 | +| 可视化新增数据 | 支持 | 支持 | +| 查看 Users、Session Manager 和 System Info | 不支持 | 支持 | +| Tools > Analyse | 不支持 | 支持 | +| Tools > Truncate | 不支持 | 支持 | + +:::note 说明 + +本表采用支持能力白名单: + +- 只有表格中明确标记为“支持”的功能属于本文支持范围。 +- 表格未列出的 DBeaver 可视化操作和管理功能均不支持。 +- 使用 MySQL 驱动时,DBeaver 界面中出现某个 MySQL 功能入口,不代表 Doris 支持该功能。 +- Users、Session Manager 和 System Info 仅支持查看,不支持通过 DBeaver 修改用户、权限或会话。 +- `Analyse` 和 `Truncate` 的支持状态仅指 MySQL 驱动中的 DBeaver Tools 菜单。使用 Apache Doris 驱动时,可以在 SQL 编辑器中执行相应的 Doris SQL。 + +::: -- 仪表盘 -- Users / user / properties -- Session Status -- Global Status +### 重要限制 -### 不支持 +两个驱动均不支持以下操作: -使用 DBeaver 管理 Apache Doris 进行某些可视化操作时可能会报错,或某些可视化操作未经验证,例如: +- 可视化修改或删除已有数据。 +- 可视化创建表。 +- 可视化新增或修改字段。 +- 可视化创建或修改 Index。 +- 可视化创建 Foreign Key 和 Trigger。 +- 可视化配置 Key Model、分区、分桶、副本数和表属性。 +- Session Status、Global Status 和 Dashboard。 +- Check、Optimize、Repair 和 Dump database。 -- 可视化创建库表 -- Schema Change -- 可视化增、删、改数据 +建议通过 SQL 编辑器执行 Doris 表结构变更以及已有数据的更新和删除。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/dbeaver.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/dbeaver.md index 6dd3d511d73d0..8e2f0d01dda99 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/dbeaver.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/dbeaver.md @@ -2,7 +2,7 @@ { "title": "DBeaver", "language": "zh-CN", - "description": "使用 DBeaver 通过 MySQL 驱动连接 Apache Doris,可视化管理 internal catalog 与 external catalog,执行 SQL 查询。" + "description": "使用 DBeaver 的 Apache Doris 驱动或 MySQL 驱动连接 Apache Doris,浏览和管理 internal catalog 与 external catalog,并执行 SQL 查询。" } --- @@ -11,117 +11,261 @@ DBeaver 是一款跨平台数据库工具,适用于开发人员、数据库管理员、分析师以及所有处理数据的用户。 -Apache Doris 高度兼容 MySQL 协议,可使用 DBeaver 的 MySQL 驱动连接 Apache Doris,并查询 internal catalog 和 external catalog 中的数据。 +Apache Doris 可通过 MySQL 协议对外提供查询服务。在包含 Apache Doris 驱动的 DBeaver 版本中,可以直接使用 `Apache Doris` 数据源入口连接 Doris,并查询 internal catalog 和 external catalog 中的数据。 + +如果当前 DBeaver 版本中没有 `Apache Doris` 驱动入口,也可以通过 MySQL 驱动连接 Apache Doris。具体操作请参考[使用 MySQL 驱动连接 Doris](#使用-mysql-驱动连接-doris)。 ## 适用场景 -- 通过可视化界面浏览 Apache Doris 的库、表、视图等元数据 -- 使用 SQL 编辑器执行查询、分析数据 -- 在同一工具中统一管理 internal catalog 与多个 external catalog -- 监控会话、查看系统变量与用户权限等运行信息 +- 通过可视化界面浏览 Apache Doris 的 catalog、database、table、view 等元数据。 +- 使用 SQL 编辑器执行查询、分析数据。 +- 在同一工具中管理 internal catalog 与 external catalog。 +- 查看会话、系统变量、用户权限等运行信息。 ## 前置条件 -- 已安装 DBeaver(推荐 24.0.0 及以上版本),下载地址:[https://dbeaver.io](https://dbeaver.io) -- 可访问的 Apache Doris 集群,并已知 FE 主机地址、查询端口、账号与密码 -- 若需通过 `catalog.db` 形式连接 external catalog,Doris 版本需为 2.1.0 及以上 +- 已安装 DBeaver 26.1.1 或更高版本,下载地址:[https://dbeaver.io](https://dbeaver.io)。 +- 可访问 Apache Doris 集群,并已知 FE 主机地址、MySQL 协议端口、账号与密码。 +- 若需通过 `catalog.db` 形式连接 external catalog,Doris 版本需为 2.1.0 及以上。 ## 操作步骤 -:::info 备注 -当前操作基于 DBeaver 24.0.0 版本验证。 +### 使用 Apache Doris 驱动连接 Doris(推荐) + +:::warning 版本要求 +DBeaver 需要升级到 26.1.1 或更高版本。 ::: -### 步骤 1:新建数据库连接 +#### 步骤 1:新建数据库连接 -1. 启动 DBeaver。 -2. 在窗口左上角单击加号(**+**)图标,或在菜单栏选择 **Database > New Database Connection**,打开 **Connect to a database** 界面。 +启动 DBeaver。 - ![添加连接 1](/images/next/connection-integration/data-integration/dbeaver/dbeaver1.png) +在窗口左上角单击加号(`+`)图标,或在菜单栏选择 `Database` > `New Database Connection`,打开 `Connect to a database` 界面。 - ![添加连接 2](/images/next/connection-integration/data-integration/dbeaver/dbeaver2.png) +![新建数据库连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg) -### 步骤 2:选择 MySQL 驱动 +#### 步骤 2:选择 Apache Doris 驱动 -在 **Select your database** 窗口中选择 **MySQL**。 +在 `Select your database` 窗口中搜索或选择 `Apache Doris`,然后单击 `Next`。 -![选择驱动](/images/next/connection-integration/data-integration/dbeaver/dbeaver3.png) +![选择 Apache Doris 驱动](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg) -### 步骤 3:配置 Doris 连接信息 +#### 步骤 3:配置 Doris 连接信息 -在 **Connection Settings** 窗口的 **Main** 标签页填写以下连接信息: +在 `Apache Doris connection settings` 窗口的 `Main` 标签页填写以下连接信息: | 配置项 | 说明 | 示例 | |--------|------|------| -| Server Host | Doris 集群的 FE 主机 IP 地址 | `127.0.0.1` | -| Port | Doris 集群的 FE 查询端口 | `9030` | -| Database | Doris 集群中的目标数据库 | `example_db` 或 `hive.example_db` | -| Username | 用于登录 Doris 集群的用户名 | `admin` | -| Password | 用于登录 Doris 集群的用户密码 | - | +| Host | Doris 集群的 FE 主机地址。如果使用 SSH 隧道,填写本地转发地址。 | `127.0.0.1` | +| Port | Doris 集群的 FE MySQL 协议端口。如果使用 SSH 隧道,填写本地转发端口。 | `9030` 或 `19030` | +| Database/Schema | 可选。Doris 集群中的目标 database,也可使用 `catalog.db` 形式连接 external catalog。 | `example_db` 或 `hive.example_db` | +| Username | 用于登录 Doris 集群的用户名。 | `admin` | +| Password | 用于登录 Doris 集群的用户密码。 | - | -:::tip Database 字段使用说明 -Database 字段可用于区分 internal catalog 与 external catalog: +`Database/Schema` 字段可用于区分 internal catalog 与 external catalog: -- 仅填写 Database 名称:当前数据源默认连接 internal catalog。 -- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog,DBeaver 中展示的库表也为该 catalog 中的库表。 +- 留空:连接建立后在 DBeaver 的 Database Navigator 中浏览 catalog 和 database。 +- 仅填写 database 名称:当前数据源默认连接 internal catalog 下的指定 database。 +- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog 下的指定 database,DBeaver 中展示的库表也为该 catalog 中的库表。 -因此,可通过创建多个 Doris 数据源来分别管理不同的 Catalog。 +:::note 备注 +通过 `catalog.db` 形式连接 Doris 的 external catalog 需要 Doris 版本在 2.1.0 及以上。 ::: -:::info 备注 +连接 internal catalog: + +![连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg) + +连接 external catalog: + +![连接 external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg) + +如需通过 DBeaver 内置 SSH 功能连接,可以单击右上角 `SSH, Proxy` 配置 SSH 隧道。如果已在本机提前建立端口转发,则在 `Host` 和 `Port` 中填写本地转发地址和端口。 + +#### 步骤 4:测试并保存连接 + +填写完连接信息后,单击左下角 `Test Connection` 验证连接信息的准确性。 + +DBeaver 弹出确认对话框后,单击 `OK` 确认配置无误。 + +单击右下角 `Finish` 完成连接配置。 + +![测试 Apache Doris 驱动连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg) + +#### 步骤 5:连接并管理数据库 + +数据库连接建立完成后,可在左侧的数据库连接导航栏看到已创建的数据源,并通过 DBeaver 浏览 Doris catalog、database、table、view 等对象。 + +![浏览 Doris 数据库对象](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg) + +#### 配置 Driver Properties + +Apache Doris 驱动底层使用 MySQL Connector/J 连接 Doris FE 的 MySQL 协议端口。驱动默认端口为 `9030`,默认用户为 `root`,JDBC URL 模板如下: + +```text +jdbc:mysql://{host}[:{port}]/[{database}] +``` + +驱动类为: + +```text +com.mysql.cj.jdbc.Driver +``` + +常见默认参数如下: + +```text +connectTimeout=20000 +rewriteBatchedStatements=true +useSSL=false +enabledTLSProtocols=TLSv1.2,TLSv1.3 +``` + +![配置 Apache Doris 驱动属性](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg) + +`useSSL=false` 表示默认不启用 TLS/SSL。若 Doris FE 的 MySQL 协议端口已正确开启 TLS,并且证书链配置正确,可在 DBeaver 的 `Driver properties` 中配置 MySQL Connector/J 的 SSL 参数,例如: + +```text +useSSL=true +sslMode=REQUIRED +``` + +如需校验证书,可配置 Java truststore,并使用: + +```text +sslMode=VERIFY_CA +trustCertificateKeyStoreUrl=file:/path/to/doris-truststore.jks +trustCertificateKeyStorePassword= +``` + +如需同时校验服务端主机名,可使用: + +```text +sslMode=VERIFY_IDENTITY +``` + +使用 `VERIFY_IDENTITY` 时,DBeaver 中填写的 Host 必须和服务端证书的 SAN/CN 匹配。 + +### 使用 MySQL 驱动连接 Doris + +如果当前 DBeaver 版本中没有 `Apache Doris` 驱动入口,可以通过 MySQL 驱动连接 Apache Doris。 + +#### 步骤 1:新建数据库连接 + +启动 DBeaver。 + +在窗口左上角单击加号(`+`)图标,或在菜单栏选择 `Database` > `New Database Connection`,打开 `Connect to a database` 界面。 + +![新建 MySQL 数据库连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg) + +#### 步骤 2:选择 MySQL 驱动 + +在 `Select your database` 窗口中选择 `MySQL`。 + +#### 步骤 3:配置 Doris 连接信息 + +在 `Connection Settings` 窗口的 `Main` 标签页填写以下连接信息: + +| 配置项 | 说明 | 示例 | +|--------|------|------| +| Server Host | Doris 集群的 FE 主机 IP 地址。 | `127.0.0.1` | +| Port | Doris 集群的 FE MySQL 协议端口。 | `9030` | +| Database | Doris 集群中的目标 database,也可使用 `catalog.db` 形式连接 external catalog。 | `example_db` 或 `hive.example_db` | +| Username | 用于登录 Doris 集群的用户名。 | `admin` | +| Password | 用于登录 Doris 集群的用户密码。 | - | + +`Database` 字段可用于区分 internal catalog 与 external catalog: + +- 仅填写 database 名称:当前数据源默认连接 internal catalog。 +- 填写格式为 `catalog.db`:当前数据源默认连接所指定 catalog,DBeaver 中展示的库表也为该 catalog 中的库表。 + +因此,可通过创建多个 Doris 数据源来分别管理不同的 catalog。 + +:::note 备注 通过 `catalog.db` 形式连接 Doris 的 external catalog 需要 Doris 版本在 2.1.0 及以上。 ::: -连接示例: +连接 internal catalog: + +![通过 MySQL 驱动连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg) -- 连接 internal catalog +连接 external catalog: - ![连接 internal catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver4.png) +![通过 MySQL 驱动连接 external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg) -- 连接 external catalog +#### 步骤 4:测试并保存连接 - ![连接 external catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver5.png) +填写完连接信息后,单击左下角 `Test Connection` 验证连接信息的准确性。 -### 步骤 4:测试并保存连接 +DBeaver 弹出确认对话框后,单击 `OK` 确认配置无误。 -1. 填写完连接信息后,单击左下角 **Test Connection** 验证连接信息的准确性。 -2. DBeaver 弹出确认对话框后,单击 **OK** 确认配置无误。 -3. 单击右下角 **Finish** 完成连接配置。 +![测试 MySQL 驱动连接](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg) -![测试连接](/images/next/connection-integration/data-integration/dbeaver/dbeaver6.png) +单击右下角 `Finish` 完成连接配置。 -### 步骤 5:连接并管理数据库 +#### 步骤 5:连接并管理数据库 数据库连接建立完成后,可在左侧的数据库连接导航栏看到已创建的数据源,并通过 DBeaver 进行连接与管理。 -![建立连接](/images/next/connection-integration/data-integration/dbeaver/dbeaver7.png) +![通过 MySQL 驱动管理数据库](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg) -## 功能支持 +## 驱动选择与功能支持 -DBeaver 对 Apache Doris 的功能支持情况如下: +### 如何选择驱动 -### 完全支持 +Apache Doris 驱动和 MySQL 驱动均通过 Doris FE 的 MySQL 协议端口连接 Doris。两个驱动的主要区别在于 DBeaver 的元数据模型、对象导航结构和管理功能入口。 -| 类别 | 功能项 | -|------|--------| -| 可视化查看 | Databases(Tables、Views)、Users | -| Administer | Session Manager | -| System Info | Session Variables、Global Variables、Engines、Charsets、User Privileges、Plugin | -| 操作类 | SQL 编辑器、SQL 控制台 | +推荐按以下原则选择驱动: -### 基本支持 +| 使用需求 | 推荐选择 | +|----------|----------| +| 日常连接 Doris、执行 SQL、浏览库表 | Apache Doris 驱动 | +| 在同一连接中浏览 internal catalog 和多个 external catalog | Apache Doris 驱动 | +| 当前 DBeaver 中没有 Apache Doris 数据源入口 | MySQL 驱动 | +| 查看 Users、Session Manager 和 System Info | MySQL 驱动 | -可点击查看且不会报错,但由于协议兼容问题,可能存在显示不全的情况: +如果只操作 internal catalog,两个驱动均可用于连接和执行 SQL,但推荐优先使用 Apache Doris 驱动。 + +### 功能对比 + +| 功能 | Apache Doris 驱动 | MySQL 驱动 | +|------|-------------------|------------| +| 连接 Doris、执行 SQL | 支持 | 支持 | +| 浏览 internal catalog | 支持 | 支持 | +| 在同一连接中浏览多个 catalog | 支持 | 不支持 | +| 在 Database Navigator 中浏览 external catalog | 支持 | 不支持 | +| 使用 `catalog.db` 作为 SQL 默认上下文 | 支持 | 支持 | +| 查看表、视图、字段和 DDL | 支持 | 支持 | +| SQL 编辑器、SQL 控制台 | 支持 | 支持 | +| 可视化查看数据 | 支持 | 支持 | +| 可视化新增数据 | 支持 | 支持 | +| 查看 Users、Session Manager 和 System Info | 不支持 | 支持 | +| Tools > Analyse | 不支持 | 支持 | +| Tools > Truncate | 不支持 | 支持 | + +:::note 说明 + +本表采用支持能力白名单: + +- 只有表格中明确标记为“支持”的功能属于本文支持范围。 +- 表格未列出的 DBeaver 可视化操作和管理功能均不支持。 +- 使用 MySQL 驱动时,DBeaver 界面中出现某个 MySQL 功能入口,不代表 Doris 支持该功能。 +- Users、Session Manager 和 System Info 仅支持查看,不支持通过 DBeaver 修改用户、权限或会话。 +- `Analyse` 和 `Truncate` 的支持状态仅指 MySQL 驱动中的 DBeaver Tools 菜单。使用 Apache Doris 驱动时,可以在 SQL 编辑器中执行相应的 Doris SQL。 + +::: -- 仪表盘 -- Users / user / properties -- Session Status -- Global Status +### 重要限制 -### 不支持 +两个驱动均不支持以下操作: -使用 DBeaver 管理 Apache Doris 进行某些可视化操作时可能会报错,或某些可视化操作未经验证,例如: +- 可视化修改或删除已有数据。 +- 可视化创建表。 +- 可视化新增或修改字段。 +- 可视化创建或修改 Index。 +- 可视化创建 Foreign Key 和 Trigger。 +- 可视化配置 Key Model、分区、分桶、副本数和表属性。 +- Session Status、Global Status 和 Dashboard。 +- Check、Optimize、Repair 和 Dump database。 -- 可视化创建库表 -- Schema Change -- 可视化增、删、改数据 +建议通过 SQL 编辑器执行 Doris 表结构变更以及已有数据的更新和删除。 diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg new file mode 100644 index 0000000000000..25c61b1812f9d Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg new file mode 100644 index 0000000000000..2a8595241d401 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg new file mode 100644 index 0000000000000..511257587f04e Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg new file mode 100644 index 0000000000000..1fc7e76a8de00 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg new file mode 100644 index 0000000000000..b9b2031a47218 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg new file mode 100644 index 0000000000000..49224dc1bd8a5 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg new file mode 100644 index 0000000000000..39f5f3ae2b596 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg new file mode 100644 index 0000000000000..feeb53c65d5d6 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg new file mode 100644 index 0000000000000..444f153e618a7 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg new file mode 100644 index 0000000000000..01001fca11000 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg new file mode 100644 index 0000000000000..639c04c9eac9b Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg differ diff --git a/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg new file mode 100644 index 0000000000000..9ab8b2e909b96 Binary files /dev/null and b/static/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg differ diff --git a/versioned_docs/version-4.x/connection-integration/data-integration/dbeaver.md b/versioned_docs/version-4.x/connection-integration/data-integration/dbeaver.md index 0fb772e9ce325..247c52c0fc8ba 100644 --- a/versioned_docs/version-4.x/connection-integration/data-integration/dbeaver.md +++ b/versioned_docs/version-4.x/connection-integration/data-integration/dbeaver.md @@ -2,126 +2,270 @@ { "title": "DBeaver", "language": "en", - "description": "Use DBeaver to connect to Apache Doris through the MySQL driver, visually manage internal catalog and external catalog, and run SQL queries." + "description": "Connect DBeaver to Apache Doris with the Apache Doris or MySQL driver, browse internal and external catalogs, and run SQL queries." } --- - + DBeaver is a cross-platform database tool for developers, database administrators, analysts, and anyone who works with data. -Apache Doris is highly compatible with the MySQL protocol, so you can use the MySQL driver in DBeaver to connect to Apache Doris and query data in the internal catalog and external catalog. +Apache Doris accepts queries through the MySQL protocol. DBeaver 26.1.1 and later include an `Apache Doris` data source that you can use to query internal and external catalogs. + +If the `Select your database` window does not list `Apache Doris`, use the MySQL driver instead. See [Connect with the MySQL driver](#connect-with-the-mysql-driver). ## Use cases -- Browse metadata such as databases, tables, and views in Apache Doris through a visual interface. -- Use the SQL editor to run queries and analyze data. -- Manage the internal catalog and multiple external catalogs in a single tool. -- Monitor sessions and view runtime information such as system variables and user privileges. +- Browse Apache Doris catalogs, databases, tables, views, and other metadata. +- Run queries and analyze data in the SQL editor. +- Manage internal and external catalogs in one tool. +- Inspect sessions, system variables, user privileges, and other runtime information. ## Prerequisites -- DBeaver is installed (version 24.0.0 or later is recommended). Download URL: [https://dbeaver.io](https://dbeaver.io) -- An Apache Doris cluster is reachable, and you know the FE host address, query port, username, and password. -- To connect to an external catalog using the `catalog.db` form, the Doris version must be 2.1.0 or later. +- Install DBeaver 26.1.1 or later from [https://dbeaver.io](https://dbeaver.io). +- You can reach the Apache Doris cluster and have the FE host address, MySQL protocol port, username, and password. +- Use Doris 2.1.0 or later to connect to an external catalog with the `catalog.db` format. + +## Connect DBeaver to Doris -## Procedure +### Connect with the Apache Doris driver (recommended) -:::info Note -The following steps are verified on DBeaver 24.0.0. +:::warning Version requirement +DBeaver 26.1.1 or later is required. ::: -### Step 1: Create a new database connection +#### Step 1: Create a database connection -1. Start DBeaver. -2. In the upper-left corner of the window, click the plus (**+**) icon, or select **Database > New Database Connection** from the menu bar to open the **Connect to a database** dialog. +Start DBeaver. - ![Add connection 1](/images/next/connection-integration/data-integration/dbeaver/dbeaver1.png) +Click the plus (`+`) icon in the upper-left corner, or select `Database` > `New Database Connection` from the menu bar. DBeaver opens the `Connect to a database` window. - ![Add connection 2](/images/next/connection-integration/data-integration/dbeaver/dbeaver2.png) +![Create a database connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-add-connection.jpg) -### Step 2: Select the MySQL driver +#### Step 2: Select the Apache Doris driver -In the **Select your database** window, select **MySQL**. +In the `Select your database` window, search for or select `Apache Doris`, then click `Next`. -![Select driver](/images/next/connection-integration/data-integration/dbeaver/dbeaver3.png) +![Select the Apache Doris driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-select-driver.jpg) -### Step 3: Configure the Doris connection +#### Step 3: Configure the Doris connection -On the **Main** tab of the **Connection Settings** window, fill in the following connection information: +On the `Main` tab of the `Apache Doris connection settings` window, enter the following values: | Field | Description | Example | -|--------|------|------| -| Server Host | The FE host IP address of the Doris cluster | `127.0.0.1` | -| Port | The FE query port of the Doris cluster | `9030` | -| Database | The target database in the Doris cluster | `example_db` or `hive.example_db` | -| Username | The username used to log in to the Doris cluster | `admin` | -| Password | The password used to log in to the Doris cluster | - | +|-------|-------------|---------| +| Host | FE host name or IP address. If you use an SSH tunnel, enter the local forwarding address. | `127.0.0.1` | +| Port | FE MySQL protocol port. If you use an SSH tunnel, enter the local forwarding port. | `9030` or `19030` | +| Database/Schema | Optional. The target database. To connect directly to an external catalog, use the `catalog.db` format. | `example_db` or `hive.example_db` | +| Username | Username for the Doris cluster. | `admin` | +| Password | Password for the Doris cluster. | - | -:::tip How to use the Database field -The Database field can be used to distinguish between the internal catalog and external catalogs: +The `Database/Schema` value determines which catalog and database DBeaver opens: -- Database name only: by default, the data source connects to the internal catalog. -- The format `catalog.db`: the data source connects to the specified catalog by default, and the databases and tables shown in DBeaver are those in that catalog. +- Leave it blank to browse catalogs and databases in the Database Navigator after connecting. +- Enter a database name to open that database in the internal catalog. +- Enter `catalog.db` to open a database in the specified external catalog. DBeaver displays the tables from that catalog and database. -Therefore, you can create multiple Doris data sources to manage different catalogs separately. +:::note +The `catalog.db` format requires Doris 2.1.0 or later. ::: -:::info Note -Connecting to a Doris external catalog with the `catalog.db` form requires Doris version 2.1.0 or later. +Connect to the internal catalog: + +![Connect to the internal catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-internal-catalog.jpg) + +Connect to an external catalog: + +![Connect to an external catalog](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-external-catalog.jpg) + +To use DBeaver's built-in SSH support, click `SSH, Proxy` in the upper-right corner and configure the tunnel. If you already created local port forwarding, enter the local address and port in `Host` and `Port`. + +#### Step 4: Test and save the connection + +Click `Test Connection` in the lower-left corner. + +When DBeaver reports a successful connection, click `OK`. + +Click `Finish` to save the connection. + +![Test the Apache Doris driver connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-test-connection.jpg) + +#### Step 5: Browse Doris objects + +The new data source appears in the Database Navigator. Expand it to browse Doris catalogs, databases, tables, and views. + +![Browse Doris objects](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-navigator.jpg) + +#### Configure driver properties + +The Apache Doris driver uses MySQL Connector/J to connect to the FE MySQL protocol port. The default port is `9030`, and the default user is `root`. The JDBC URL template is: + +```text +jdbc:mysql://{host}[:{port}]/[{database}] +``` + +The driver class is: + +```text +com.mysql.cj.jdbc.Driver +``` + +By default, the driver sets: + +```text +connectTimeout=20000 +rewriteBatchedStatements=true +useSSL=false +enabledTLSProtocols=TLSv1.2,TLSv1.3 +``` + +![Configure Apache Doris driver properties](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-doris-driver-properties.jpg) + +`useSSL=false` disables TLS/SSL by default. If the FE MySQL protocol port has TLS enabled and the certificate chain is configured correctly, set the MySQL Connector/J SSL properties under `Driver properties`. For example: + +```text +useSSL=true +sslMode=REQUIRED +``` + +To verify the certificate authority, configure a Java truststore: + +```text +sslMode=VERIFY_CA +trustCertificateKeyStoreUrl=file:/path/to/doris-truststore.jks +trustCertificateKeyStorePassword= +``` + +To also verify the server host name, use: + +```text +sslMode=VERIFY_IDENTITY +``` + +With `VERIFY_IDENTITY`, the `Host` value in DBeaver must match the certificate's SAN or CN. + +### Connect with the MySQL driver + +If the `Select your database` window does not list `Apache Doris`, connect with the MySQL driver. + +#### Step 1: Create a database connection + +Start DBeaver. + +Click the plus (`+`) icon in the upper-left corner, or select `Database` > `New Database Connection` from the menu bar. DBeaver opens the `Connect to a database` window. + +![Create a MySQL database connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-add-connection.jpg) + +#### Step 2: Select the MySQL driver + +In the `Select your database` window, select `MySQL`. + +#### Step 3: Configure the Doris connection + +On the `Main` tab of the `Connection Settings` window, enter the following values: + +| Field | Description | Example | +|-------|-------------|---------| +| Server Host | FE host name or IP address. | `127.0.0.1` | +| Port | FE MySQL protocol port. | `9030` | +| Database | Target database. To connect directly to an external catalog, use the `catalog.db` format. | `example_db` or `hive.example_db` | +| Username | Username for the Doris cluster. | `admin` | +| Password | Password for the Doris cluster. | - | + +The `Database` value determines the default catalog: + +- Enter a database name to open that database in the internal catalog. +- Enter `catalog.db` to open a database in the specified external catalog. DBeaver displays the tables from that catalog and database. + +Create separate Doris data sources if you need direct access to several catalogs. + +:::note +The `catalog.db` format requires Doris 2.1.0 or later. ::: -Connection examples: +Connect to the internal catalog: + +![Connect to the internal catalog with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-internal-catalog.jpg) + +Connect to an external catalog: -- Connect to the internal catalog +![Connect to an external catalog with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-external-catalog.jpg) - ![Connect to internal catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver4.png) +#### Step 4: Test and save the connection -- Connect to an external catalog +Click `Test Connection` in the lower-left corner. - ![Connect to external catalog](/images/next/connection-integration/data-integration/dbeaver/dbeaver5.png) +When DBeaver reports a successful connection, click `OK`. -### Step 4: Test and save the connection +![Test the MySQL driver connection](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-test-connection.jpg) -1. After filling in the connection information, click **Test Connection** in the lower-left corner to verify that the information is correct. -2. When DBeaver displays a confirmation dialog, click **OK** to confirm that the configuration is correct. -3. Click **Finish** in the lower-right corner to complete the connection setup. +Click `Finish` to save the connection. -![Test connection](/images/next/connection-integration/data-integration/dbeaver/dbeaver6.png) +#### Step 5: Manage the database -### Step 5: Connect to and manage the database +The new data source appears in the Database Navigator. Use it to connect to and manage the database. -After the database connection is established, you can see the new data source in the database connection navigator on the left, and connect to and manage it through DBeaver. +![Manage the database with the MySQL driver](/images/next/connection-integration/data-integration/dbeaver-new/dbeaver-mysql-navigator.jpg) -![Establish connection](/images/next/connection-integration/data-integration/dbeaver/dbeaver7.png) +## Driver selection and feature support -## Feature support +### Choose a driver -DBeaver supports Apache Doris features as follows: +Both the Apache Doris driver and the MySQL driver connect to Doris through the FE MySQL protocol port. They differ mainly in how DBeaver models metadata, organizes objects in the navigator, and exposes administration features. -### Fully supported +Use the following guidelines to select a driver: -| Category | Feature | -|------|--------| -| Visual viewing | Databases (Tables, Views), Users | -| Administer | Session Manager | -| System Info | Session Variables, Global Variables, Engines, Charsets, User Privileges, Plugin | -| Operations | SQL editor, SQL console | +| Use case | Recommended driver | +|----------|--------------------| +| Connect to Doris, run SQL, and browse databases and tables | Apache Doris driver | +| Browse the internal catalog and multiple external catalogs in one connection | Apache Doris driver | +| The current DBeaver version does not provide an Apache Doris data source | MySQL driver | +| View Users, Session Manager, and System Info | MySQL driver | -### Basically supported +If you only work with the internal catalog, either driver can connect to Doris and execute SQL. However, the Apache Doris driver is recommended. -You can click and view these items without errors, but due to protocol compatibility issues, some content may not be fully displayed: +### Feature comparison + +| Feature | Apache Doris driver | MySQL driver | +|---------|---------------------|--------------| +| Connect to Doris and execute SQL | Supported | Supported | +| Browse the internal catalog | Supported | Supported | +| Browse multiple catalogs in one connection | Supported | Not supported | +| Browse external catalogs in Database Navigator | Supported | Not supported | +| Use `catalog.db` as the default SQL context | Supported | Supported | +| View tables, views, columns, and DDL | Supported | Supported | +| SQL editor and SQL console | Supported | Supported | +| View data through the UI | Supported | Supported | +| Insert data through the UI | Supported | Supported | +| View Users, Session Manager, and System Info | Not supported | Supported | +| Tools > Analyse | Not supported | Supported | +| Tools > Truncate | Not supported | Supported | + +:::note Support scope + +This table defines supported capabilities using an allowlist: + +- Only features explicitly marked as "Supported" in the table are within the scope of this document. +- DBeaver UI operations and administration features not listed in the table are not supported. +- When you use the MySQL driver, the presence of a MySQL feature in the DBeaver interface does not mean that Doris supports it. +- Users, Session Manager, and System Info are read-only. You cannot use DBeaver to modify users, privileges, or sessions. +- Support for `Analyse` and `Truncate` applies only to the DBeaver Tools menu when you use the MySQL driver. With the Apache Doris driver, run the corresponding Doris SQL statements in the SQL editor. + +::: -- Dashboard -- Users / user / properties -- Session Status -- Global Status +### Important limitations -### Not supported +Neither driver supports the following operations: -When using DBeaver to manage Apache Doris, certain visual operations may report errors or have not been verified, for example: +- Update or delete existing data through the UI. +- Create tables through the UI. +- Add or modify columns through the UI. +- Create or modify indexes through the UI. +- Create foreign keys or triggers through the UI. +- Configure key models, partitions, buckets, replica counts, or table properties through the UI. +- Session Status, Global Status, or Dashboard. +- Check, Optimize, Repair, or Dump database. -- Visually creating databases and tables -- Schema Change -- Visually inserting, deleting, or updating data +Use the SQL editor to change Doris table schemas and to update or delete existing data.