1. 概述

本文档详细介绍了如何在 DBeaver 中配置和使用 Excel JDBC 驱动（XLSQL），以实现对 Excel 文件的 SQL 化查询与操作。通过该驱动，用户可以像操作传统数据库一样管理 Excel 数据。

项目地址：https://github.com/daichangya/xlsql

2. 准备工作

2.1 环境与系统要求

在开始之前，请确保您的环境满足以下要求：

  • DBeaver 版本：21.0 或更高版本

  • Java 环境：

    • DBeaver 自带 Java 运行时（通常为 Java 11 或更高版本），无需单独安装 Java。
    • XLSQL JDBC 驱动需要 Java 8+，DBeaver 自带的 Java 环境已满足此要求。
    • 注：仅在极少数情况下（如 DBeaver 自带 Java 版本低于 8），才需要单独安装 Java 8+。
  • 操作系统：Windows 7+, macOS 10.12+, Linux (大多数发行版)

  • 硬件资源：

    • 内存：建议至少 2GB RAM
    • 磁盘空间：至少 500MB 可用空间
  • 驱动文件：Excel JDBC 驱动 JAR 文件（xlsql）

2.2 下载和安装 DBeaver

DBeaver 是一款免费的通用数据库管理工具，支持多种数据库系统。

下载地址

安装步骤

  • Windows:

    1. 下载 Windows 安装包（.zip 或 .exe）。
    2. 解压到目标目录或运行安装程序。
    3. 运行 dbeaver.exe 启动 DBeaver。

  • macOS:

    1. 下载 .dmg 文件。
    2. 双击打开，将 DBeaver 拖拽到 Applications 文件夹。
    3. 从应用程序中启动 DBeaver。

  • Linux:

    1. 下载 .tar.gz 文件。
    2. 解压：tar -xzf dbeaver-ce-*.tar.gz
    3. 进入解压目录，运行：./dbeaver

2.3 获取 Excel JDBC 驱动

方式一：从 Maven Central 获取（推荐）

XLSQL 5.1.1 已发布到 Maven Central，可以直接通过 Maven 依赖使用：

<dependency>
    <groupId>io.github.daichangya</groupId>
    <artifactId>xlsql</artifactId>
    <version>5.1.1</version>
</dependency>

方式二：手动下载 JAR 文件

从 Maven Central 直接下载 JAR 文件：

3. 在 DBeaver 中配置 Excel JDBC 驱动

3.1 打开驱动管理器

  1. 启动 DBeaver。
  2. 点击菜单栏 Database → Driver Manager。

3.2 创建新驱动

  1. 点击 New 按钮创建新驱动。

  2. 在 Settings 标签页中填写以下信息：

    • Driver Name: Excel JDBC Driver
    • Class Name: io.github.daichangya.xlsql.jdbc.xlDriver
    • URL Template: jdbc:xlsql:excel:{path}
    • Port: (留空)

dbeaver1

3.3 添加驱动文件

  1. 切换到 Libraries 标签页。
  2. 点击 Add File 按钮。

  3. 选择之前下载的 Excel JDBC 驱动 JAR 文件。

    • 路径示例：/path/to/xlsql-5.1.1.jar
  4. 点击 OK 保存驱动配置。

4. 创建数据库连接

4.1 新建连接

  1. 点击 Database → New Database Connection。
  2. 在连接类型列表中选择 Generic → Generic JDBC。
  3. 点击 Next。

4.2 配置连接参数

  1. Driver: 选择之前创建的 "Excel JDBC Driver"。

  2. JDBC URL: 输入 Excel 文件所在的文件夹路径（注意：是文件夹路径，而非单个文件路径）。

    jdbc:xlsql:excel:/path/to/excel/folder

    示例：

    jdbc:xlsql:excel:/Users/username/Documents

4.3 测试连接

  1. 点击 Test Connection 按钮。
  2. 如果配置正确，会显示 "Connected" 消息。
  3. 点击 Finish 完成连接创建。

5. 使用 Excel JDBC 驱动

5.1 浏览数据结构

连接成功后，您可以在 DBeaver 的数据库导航器中看到以下结构：

  • 数据库：对应指定的 Excel 文件夹。
  • 数据表：每个 Excel 工作表（Sheet）作为一张表显示。
  • 列：表的列对应 Excel 中的第一行标题。

5.2 执行 SQL 查询

在 SQL 编辑器中可以执行标准 SQL 查询。建议使用下划线格式，表名和字段名通常无需引号。

-- 查询所有数据
SELECT * FROM test1_Sheet1;

-- 条件查询
SELECT * FROM test1_Sheet1 WHERE column1 = 'value';

-- 聚合查询
SELECT COUNT(*) FROM test1_Sheet1;

-- 排序查询
SELECT * FROM test1_Sheet1 ORDER BY column1;

dbeaver2-n9ho.png

6. Excel 文件要求

6.1 文件格式

  • 支持 .xls 和 .xlsx 格式。

6.2 工作表结构

  1. 第一行为列标题：驱动会将第一行识别为字段名。
  2. 命名规范：标题应使用有效的 SQL 标识符。
  3. 字符限制：避免使用特殊字符和空格。
  4. 数据类型：每列应保持数据类型一致，以避免解析错误。

6.3 示例 Excel 结构

NameAgeCity
John25New York
Jane30Los Angeles

7. 常见问题和解决方案

7.1 连接失败

  • 问题: Cannot invoke "String.length()" because "<parameter1>" is null

  • 解决方案:

    • 检查 JDBC URL 中的文件路径是否正确。
    • 确保 Excel 文件存在且路径可访问。

7.2 驱动未找到

  • 问题: Driver class not found

  • 解决方案:

    • 确认驱动 JAR 文件已正确添加到驱动配置的 Libraries 中。
    • 检查驱动类名是否正确：io.github.daichangya.xlsql.jdbc.xlDriver。

7.3 权限问题

  • 问题: Permission denied 访问 Excel 文件

  • 解决方案:

    • 检查文件系统的读写权限。
    • 确保 DBeaver 进程有权限访问目标文件夹。

7.4 中文字符乱码

  • 解决方案:

    • 确保 Excel 文件保存时使用 UTF-8 编码。
    • 在连接参数中指定字符集（见高级配置）。

8. 高级配置

8.1 连接属性

可以在连接配置中设置以下属性以优化行为：

  • charset: 指定字符集编码（例如 UTF-8）。
  • readonly: 设置只读模式（例如 true）。

8.2 性能优化

  • 对于大型 Excel 文件，建议在 SQL 中使用过滤条件（WHERE）以减少数据加载量。
  • 避免在包含复杂公式的工作表上执行查询，建议将公式结果转换为静态值。

9. 限制和注意事项

9.1 功能限制

  1. 不支持复杂的数据类型（如图片、图表、宏等）。
  2. 不支持 Excel 公式的实时计算。
  3. 对超大文件的查询性能可能较差。
  4. 并发访问支持有限，不建议多进程同时写入同一文件。

9.2 数据类型映射

Excel 类型SQL 类型
文本VARCHAR
数字NUMERIC
日期DATE
布尔值BOOLEAN

9.3 最佳实践

  1. 定期备份重要的 Excel 文件。
  2. 在执行写操作前，确认文件未被其他程序（如 Excel 软件）占用。
  3. 避免在生产环境中直接修改原始数据文件，建议使用副本。
  4. 先在测试文件上验证 SQL 逻辑。

10. 故障排除

10.1 日志查看

  1. 在 DBeaver 中打开 Window → Show View → Error Log。
  2. 查看详细的错误堆栈信息以定位问题。

10.2 启用调试模式

在启动 DBeaver 时添加调试参数以便获取更多信息：

dbeaver -vmargs -Dorg.jkiss.dbeaver.debug=true

10.3 联系支持

如果遇到无法解决的问题，请在反馈时提供以下信息：

  • 完整的错误日志。
  • 使用的 Excel 文件示例（脱敏后）。
  • DBeaver 版本和 XLSQL 驱动版本信息。

说明：本文档基于 DBeaver 21.0+ 及 XLSQL 5.1.1 版本编写。不同版本界面或特性可能略有差异，请以实际软件为准。