# 使用 DBeaver 连接 EMQX Tables

[DBeaver](https://dbeaver.io/) 是跨平台数据库管理工具。
EMQX Tables 支持通过 PostgreSQL 或 Arrow Flight SQL 驱动连接 DBeaver，浏览并查询数据库。

## 前提条件

- 已安装 DBeaver。
- 已进入目标 Tables 部署的**集成与客户端**页面，并点击 **DBeaver** 打开当前部署的连接指南。
- 客户端可通过所选协议对应的地址和端口访问部署。

## 使用 PostgreSQL 连接

1. 打开 DBeaver，点击**新建数据库连接**。
2. 选择 **PostgreSQL**，根据提示安装驱动。
3. 填写以下连接参数：

   | 参数 | 值 |
   | --- | --- |
   | 主机 | Tables 公网域名 |
   | 端口 | `4003` |
   | 数据库 | 部署中的数据库名称，例如 `public` |
   | 用户名 | 部署连接信息中显示的用户名 |
   | 密码 | 该部署连接信息中显示的密码 |

4. 在 SSL 设置中启用加密连接，将 SSL 模式设为 `require`。
5. 点击**测试连接**，确认成功后点击**完成**保存连接。

如需验证服务端身份，请配置受信任 CA 和主机名校验。TLS 参数说明参见 [PostgreSQL 连接指南](./emqx_tables_with_postgresql.md)。

## 使用 Arrow Flight SQL 连接

DBeaver 需要先配置 Arrow Flight SQL JDBC 驱动，再创建连接。

### 添加驱动

1. 准备 Arrow Flight SQL JDBC Driver 19.0.0 的驱动包，Maven 坐标为 `org.apache.arrow:flight-sql-jdbc-driver:19.0.0`。
2. 在 DBeaver 中打开**数据库** -> **驱动管理器**，点击**新建**。
3. 配置驱动参数：

   | 参数 | 值 |
   | --- | --- |
   | 驱动名称 | `EMQX Tables` |
   | 驱动类型 | `Generic` |
   | 类名 | `org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver` |
   | URL 模板 | `jdbc:arrow-flight-sql://{host}:{port}?useEncryption=true` |
   | 默认端口 | `5001` |

4. 在**库**页签中添加驱动包，点击**找到类**确认上述类可识别。
5. 点击**确定**保存驱动。

驱动及连接属性说明参见 [Apache Arrow Flight SQL JDBC 文档](https://arrow.apache.org/java/current/flight_sql_jdbc_driver.html)。
如启动或查询时出现 Java 模块访问错误，请按驱动要求为 DBeaver 的 JVM 添加 `--add-opens=java.base/java.nio=ALL-UNNAMED`，重启后再测试。

### 创建连接

1. 新建数据库连接，选择刚创建的 **EMQX Tables** 驱动。
2. 配置 JDBC URL：

   ```text
   jdbc:arrow-flight-sql://{HOST}:5001?useEncryption=true
   ```

3. 填写该部署连接信息中显示的用户名和密码。
4. 按客户端要求配置证书信任，保留 `useEncryption=true`。
5. 点击**测试连接**，成功后点击**完成**。

不要为了绕过证书错误而关闭加密或验证。请检查域名与证书是否匹配，并正确导入受信任的 CA。

## 验证查询

打开连接的 SQL 编辑器，先执行：

```sql
SELECT 1;
```

如果已完成快速开始，可用数据库限定名查询目标表，避免默认数据库选择错误：

```sql
SELECT * FROM public.machine_metrics ORDER BY ts DESC LIMIT 10;
```

连接成功但工具中的部分数据库管理操作失败时，应确认该操作是否依赖 Tables 未提供的 PostgreSQL 功能。