随着大模型（LLM）在企业级数据分析中的应用日益广泛，Text-to-SQL 技术正从“简单的 SQL 生成”向“理解业务语义”演进。作为其中的佼佼者，WrenAI 通过引入“语义层（Semantic Layer）”解决了 LLM 难以理解复杂表结构的问题。

但在实际应用中，企业的数据往往存储在各种各样的引擎中。虽然 WrenAI 已经支持了 DuckDB、MySQL、PostgreSQL、BigQuery 等主流数据库，但如果你使用的是某种国产数据库、时序数据库或公司自研的查询引擎，该怎么办？

本文将带你深入 WrenAI 的核心代码库，手把手教你如何通过二次开发，为 WrenAI 增加一个自定义数据源适配器。

---

1. 核心架构：WrenAI 是如何连接数据的？

在开始编码前，我们需要了解 WrenAI 的基本组成：

• Wren AI Service (Python)：负责与 LLM 交互、意图解析。

• Wren UI (TypeScript)：用户操作界面。

• Wren Engine (Java/Kotlin)：这是我们要改造的核心。它负责管理语义模型、维护元数据，并最终将逻辑查询翻译成特定数据库的 SQL 语句。

数据源适配（Connector） 的核心逻辑位于 Wren Engine 中。Wren Engine 参考了类似 Trino 的插件化设计，通过抽象层屏蔽了不同数据库的差异。

---

2. 准备工作

• 代码仓库：克隆 Canner/WrenAI。

• 开发环境：JDK 17+, Maven 3.8+。

• 核心模块：重点关注 wren-main 和 wren-base 模块。

---

3. 核心步骤：实现自定义适配器

增加一个新数据源（假设我们叫它 MyCustomDB）通常需要以下四个步骤：

第一步：定义 Connector 配置项

在 wren-main 模块中，你需要定义连接该数据库所需的参数（如 URL、User、Password 等）。

1. 在 io.wren.main.connector 包下创建配置类。

2. 使用 Jackson 注解定义配置格式，确保 UI 传递的参数能正确解析。

Java

public class MyCustomConfig {
    private String host;
    private int port;
    // ... getters and setters
}

第二步：实现 Connector 接口

Connector 是 Wren Engine 与外部数据库通信的桥梁。你需要实现两个关键组件：

1. ConnectorMetadata：告诉 WrenAI 这个数据库里有哪些 Schema、哪些表、哪些列。

   • 你需要实现 listTables(), getTableMetadata() 等方法。

   • 核心逻辑：调用你目标数据库的 JDBC 或 API 获取元数据。

2. ConnectorRecordIterator：定义如何执行 SQL 并获取结果。

   • WrenAI 通常会将 SQL 发送到目标库执行，你需要处理连接池和结果集转换。

第三步：SQL 方言（Dialect）适配

不同数据库的 SQL 语法（如分页、日期函数、引号转义）各不相同。WrenAI 使用 Calcite 或内部的 SqlFormatter 处理转换。

你需要检查 wren-base 中的 SqlDialect 类，并为 MyCustomDB 增加特定的方言实现：

• 引符号：是 " 还是 `？

• 函数映射：比如 SUBSTR 在你的库里是不是叫 SUBSTRING？

第四步：注册 Connector Factory

为了让系统识别你的新适配器，你需要在 ConnectorManager 中注册它。

Java

// 在 ConnectorManager 中增加类似如下逻辑
if (type.equals("my_custom_db")) {
    return new MyCustomConnectorFactory().create(config);
}

---

4. UI 层的配合（可选但推荐）

为了让用户能在界面上看到你的新数据源，你需要修改 wren-ui 模块：

1. 增加图标：在 /assets/icons 下放入数据库 Logo。

2. 修改连接表单：在 DataSourceForm 中增加对 MyCustomDB 类型支持，定义表单字段（Host, Port 等）。

---

5. 调试与验证

建议的调试路径如下：

1. 单元测试：在 wren-main 中编写单元测试，模拟 ConnectorMetadata 获取表结构的过程。

2. 集成测试：

   • 启动你自定义数据库的 Docker 容器。

   • 编译并运行 Wren Engine。

   • 使用 Postman 直接调用 Wren Engine 的 API /v1/connector，验证能否成功连接并拉取 Schema。

3. 端到端测试：启动 Wren AI Service 和 UI，尝试在界面上配置该数据源并进行提问。

---

6. 为什么这种二次开发很有价值？

为 WrenAI 增加适配器不仅仅是为了“能查到数据”，其真正的威力在于：

• 统一语义层：一旦适配成功，你可以在 WrenAI 中定义复杂的语义关联（Relationship），LLM 就能在你的自定义数据库上实现复杂的跨表 Join。

• 权限与安全：通过 WrenAI 的中转，你可以对底层数据库进行更细粒度的访问控制。

• 零代码 BI：为非技术同事提供一个基于你特定业务库的自然语言查询接口。

---

总结

WrenAI 的模块化设计使得扩展数据源变得相对清晰。核心在于 Java 端的 Connector 接口实现 以及 SQL 方言的兼容。