使用指南

快速开始

XLSQL 允许您像操作数据库一样操作 Excel 文件。只需几个简单的步骤即可集成到您的 Java 项目中。

依赖配置

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

在您的 pom.xml 中添加以下依赖：

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

在 Maven Central 查看

JDBC 使用示例

XLSQL 完全遵循 JDBC 标准，以下是一个完整的查询示例：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class ExcelQuery {
    public static void main(String[] args) throws Exception {
        // 1. 注册驱动
        Class.forName("io.github.daichangya.xlsql.jdbc.xlDriver");

        // 2. 创建连接
        // URL 格式: jdbc:xlsql:excel:/path/to/directory
        String url = "jdbc:xlsql:excel:/data/excel_files";
        try (Connection conn = DriverManager.getConnection(url);
             Statement stmt = conn.createStatement()) {
            
            // 3. 执行查询
            // 表名格式: "文件名.工作表名" (注意引号)
            String sql = "SELECT * FROM sales_2024_Sheet1 WHERE amount > 1000";
            try (ResultSet rs = stmt.executeQuery(sql)) {
                while (rs.next()) {
                    System.out.println("Customer: " + rs.getString("Customer"));
                    System.out.println("Amount: " + rs.getDouble("Amount"));
                }
            }
        }
    }
}

DBeaver 使用指南

DBeaver 是一个免费的通用数据库管理工具，您可以使用它来可视化查询和管理 Excel 文件。

下载 DBeaver

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

下载 DBeaver

配置 Excel JDBC 驱动

步骤 1：下载驱动 JAR 文件

从 Maven Central 下载 Shaded JAR（推荐，包含所有依赖）：

步骤 2：在 DBeaver 中配置驱动

  1. 启动 DBeaver，点击菜单栏 Database → Driver Manager
  2. 点击 New 按钮创建新驱动
  3. 在 Settings 标签页中填写：
    • Driver Name: Excel JDBC Driver
    • Class Name: io.github.daichangya.xlsql.jdbc.xlDriver
    • URL Template: jdbc:xlsql:excel:{path}
  4. 切换到 Libraries 标签页，点击 Add File，选择下载的 JAR 文件
  5. 点击 OK 保存驱动配置

步骤 3：创建数据库连接

  1. 点击 Database → New Database Connection
  2. 选择 Generic → Generic JDBC
  3. 选择之前创建的 "Excel JDBC Driver"
  4. 在 JDBC URL 中输入 Excel 文件所在目录路径： 
    jdbc:xlsql:excel:/path/to/your/excel/files

    示例：jdbc:xlsql:excel:/Users/username/Documents

  5. 点击 Test Connection 测试连接
  6. 连接成功后点击 Finish

使用 DBeaver 查询 Excel

连接成功后，您可以在 DBeaver 中：

  • 浏览 Excel 文件结构（文件作为数据库，工作表作为表）
  • 在 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;

-- JOIN 查询
SELECT 
    c.customer_name,
    o.order_id,
    o.amount
FROM customers_Sheet1 c
JOIN orders_Sheet1 o ON c.customer_id = o.customer_id;
表名格式说明：表名格式为 文件名_工作表名（使用下划线连接，文件名不包含扩展名）。

常见问题

解决： 确认驱动 JAR 文件已正确添加到驱动配置的 Libraries 标签页中，建议使用 Shaded JAR（包含所有依赖）。

解决： 检查 JDBC URL 中的文件路径是否正确，确保路径存在且 DBeaver 有访问权限。

解决： 确认表名格式为 文件名_工作表名（下划线连接，文件名不包含扩展名），例如文件 sales.xlsx 的工作表 Sheet1 表示为 sales_Sheet1。
提示：DBeaver 提供了强大的可视化界面，让您无需编写代码即可查询和管理 Excel 数据。更多详细信息请参考 DBeaver 官方文档。

配置说明

您可以通过环境变量或系统属性来配置 XLSQL。

环境变量

变量名 描述
XLSQL_CONFIG_PATH 配置文件路径
XLSQL_LOG_PATH 日志文件路径

配置文件 (xlsql_config.properties)

默认位置：~/.xlsql/xlsql_config.properties

# 数据库引擎 (hsqldb, h2 或 native)
engine=hsqldb

# HSQLDB 配置
hsqldb.url=jdbc:hsqldb:mem:xlsql
hsqldb.user=sa
hsqldb.password=

# H2 配置（可选）
h2.url=jdbc:h2:mem:xlsql
h2.user=sa
h2.password=

常见问题

解决： 确保 XLSQL JAR 包已正确添加到项目的 classpath 中。如果是 Maven 项目，请检查依赖是否下载成功。

解决： 检查 JDBC URL 中的路径是否正确。确保该路径在文件系统中存在，且应用程序有读取权限。

解决：
  • 确保 Excel 文件存在于连接的目录中。
  • 表名格式必须为 "文件名.工作表名"，例如 "test_Sheet1"。
  • 文件名不包含扩展名（.xls/.xlsx）。
  • 注意 SQL 中的引号和大小写敏感性。