DBeaver Community 可以通过 Apache Arrow Flight SQL JDBC Driver 连接 TSDB 专享版，浏览业务访问令牌有权读取的 Database、Table 和字段，并执行 SQL 查询。

版本要求

准备连接信息

配置连接前，请准备：

• 集群详情页显示的访问地址和服务端口。
• 目标 Database 名称。
• 对目标 Database 或 Table 具有 read 权限的业务访问令牌。
• Apache Arrow Flight SQL JDBC Driver。Maven 坐标为 org.apache.arrow:flight-sql-jdbc-driver。

建议使用内网地址，并为 DBeaver 单独创建一个业务访问令牌，只授予需要读取的 Database 或 Table 权限。如果通过公网连接，请先为集群绑定 EIP，并确保本机能够访问该公网地址。

TSDB 专享版当前不支持 HTTPS/TLS，连接内容为明文传输。连接方式和安全边界请参见连接地址与认证。

添加 JDBC 驱动

1. 打开 DBeaver，进入 Driver Manager。
2. 新建驱动，将驱动名称设置为便于识别的名称，例如 Arrow Flight SQL。
3. 在 Libraries 中添加 flight-sql-jdbc-driver 19.0.0 或更高版本的 JAR 文件。

4. 将 Driver Class 设置为：

   Text 复制

   1org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver

5. 保存驱动配置。

请从 Apache Arrow 官方发布渠道或 Maven Central 获取驱动，不要使用来源不明的 JAR 文件。

创建连接

1. 使用刚添加的驱动新建连接。

2. 按以下格式填写 JDBC URL：

   Text 复制

   1jdbc:arrow-flight-sql://<访问地址>:<端口>?useEncryption=false&database=<Database>&token=<业务访问令牌>

3. 将 <访问地址>、<端口>、<Database> 和 <业务访问令牌> 替换为实际值。
4. 单击 Test Connection。连接成功后保存配置。

database 用于选择 SQL 查询的目标 Database。不要省略该参数，也不要把业务访问令牌写入查询语句、连接名称或共享文档。DBeaver 会保存连接配置；不要导出或共享包含令牌的连接配置文件。

浏览 Table 和字段

连接成功后，在 Database Navigator 中展开目标 Database 和 public Schema，即可查看当前令牌有权读取的 Table 和字段。

如果业务访问令牌只具有一个 Database 的读取权限，Navigator 只显示该授权范围内的资源。需要访问多个 Database 时，应为令牌分别授予所需权限，不要使用管理员访问令牌代替最小权限的业务访问令牌。

执行 SQL 查询

在目标连接中打开 SQL Editor，选择要查询的 Database 后执行 SQL。例如：

1SELECT time, device, temperature
2FROM sensor_metrics
3ORDER BY time DESC
4LIMIT 100;

将 sensor_metrics、device 和 temperature 替换为实际的 Table、Tag 和 Field。

也可以在 Navigator 中右键单击目标 Table，使用 DBeaver 的 Generate SQL → SELECT 生成查询。运行前检查查询中的字段、排序和返回行数是否符合需要。

完整 SQL 语法和函数请参见SQL 查询语言参考。

常见问题

Test Connection 失败

• 检查集群状态、访问地址、服务端口，以及本机到集群的网络连通性。
• 确认 JDBC URL 中包含 useEncryption=false 和正确的 database。
• 确认业务访问令牌有效，并具有目标 Database 或 Table 的 read 权限。
• 确认使用的是 Arrow Flight SQL JDBC Driver 19.0.0 或更高版本，Driver Class 填写正确。

提示缺少 database

检查 JDBC URL 是否包含：

1database=<Database>

连接测试成功但执行 SQL 时提示缺少 database，通常表示 URL 没有指定目标 Database。

Navigator 中没有目标 Table 或字段

• 确认 JDBC URL 中的 Database 名称正确。
• 检查业务访问令牌对目标 Table 是否具有 read 权限。
• 如果 Table 刚通过写入创建，稍后刷新 Navigator 再试，实际同步时间可能受集群运行状态影响。

查询成功但返回 0 行

• 检查 Table 是否已有数据。
• 检查查询条件是否排除了目标数据。
• 检查 Database 或 Table 的数据保留期，超过保留期的数据不会返回。