添加新数据库方言

2025年7月7日大约 4 分钟

添加新数据库方言

本文档详细介绍如何添加新的数据库方言支持，包括完整的步骤、示例和最佳实践。

添加步骤

要添加新的数据库方言支持，请按照以下步骤操作：

在/data/jdbc/目录下创建一个新的TOML文件，命名为{数据库名}.toml，例如polardb.toml
参考现有的方言配置文件，填写新数据库的相关配置：
- JDBC连接信息
- 数据类型映射
- 元数据查询SQL
- SQL模板
- 数据库特性
在hetu.toml文件的[database]部分添加新数据库的信息：

[database]
polardb = { name = 'polardb', description = "PolarDB数据库" }

注意： 确保键名polardb与配置文件名polardb.toml一致（不含后缀），保持完全一致。这是系统正确识别和加载方言配置的关键。

根据需要，在hetu.toml的其他部分添加相关配置：

# 添加到数据库分类
[categories.group]
relational = ['mysql', 'postgresql', 'oracle', 'polardb', '...']

# 设置安装配置
[install]
polardb = true

# 如果新数据库与现有数据库相似，可以设置继承关系
[extend]
polardb = { type = "postgresql" }  # 表示polardb继承postgresql的配置

完整示例

以下是添加一个名为"PolarDB"的数据库方言的完整示例：

1. 创建`polardb.toml`文件：

# polardb.toml

[jdbc]
driverClass = "com.polardb.jdbc.Driver"
validationQuery = "SELECT 1"
urlPrefix = "jdbc:polardb"
hibernateDialect = "org.hibernate.dialect.PolarDBDialect"
calciteDialect = "org.apache.calcite.sql.dialect.PolarDBDialect"
url = "jdbc:polardb://{host}:{port}/{databaseName}"

[jdbc.urlProperties]
useSSL = "false"
characterEncoding = "utf-8"

[type.VARCHAR]
expr = "VARCHAR({length})"
length = { min = 0, max = 8000 }

[type.LONGVARCHAR]
expr = "TEXT"

[metadata]
schema = "SELECT CURRENT_SCHEMA()"
catalog = "SELECT CURRENT_DATABASE()"
column = """SELECT
                column_name AS columnName,
                data_type AS columnType,
                character_maximum_length AS columnLength,
                numeric_precision AS columnPrecision,
                numeric_scale AS columnScale,
                CASE WHEN is_nullable = 'YES' THEN 1 ELSE 0 END AS isNullable,
                CASE WHEN column_key = 'PRI' THEN 1 ELSE 0 END AS isPrimaryKey,
                column_default AS defaultValue,
                column_comment AS remark,
                ordinal_position AS orderNo
            FROM information_schema.columns
            WHERE table_schema = '{schema}' AND table_name = '{tableName}'
            ORDER BY ordinal_position"""
tables = """SELECT 
                table_name AS tableName, 
                table_comment AS comment 
            FROM information_schema.tables 
            WHERE table_schema = '{schema}' AND table_type = 'BASE TABLE'"""

[template]
limit = "{sql} LIMIT {limit} OFFSET {offset}"
notNullExpr = "NOT NULL"
defaultExpr = "DEFAULT"
addComment = true
tableComment = """tableComment(tableName, comment) ::= <<
COMMENT ON TABLE {tableName} IS '{comment}';
>>"""
columnComment = """columnComment(columns, tableName ) ::= <<
{columns:{c |COMMENT ON COLUMN {tableName}.{c.columnName} IS '{c.remark}';}; separator="
"}
>>"""

[characteristic]
implicitTypeConversion = true
literalQuote = "'"
identifierQuote = "\""

2. 在`hetu.toml`中添加新数据库信息：

[database]
# 其他数据库配置...
polardb = { name = 'polardb', description = "PolarDB数据库" }

[categories.group]
relational = ['mysql', 'postgresql', 'oracle', 'polardb', '...']
# 其他分类...

[install]
# 其他数据库...
polardb = true

利用继承机制简化配置

如果新数据库与现有数据库高度兼容（如PolarDB与PostgreSQL），可以利用继承机制大幅简化配置：

在hetu.toml中设置继承关系：

[extend]
polardb = { type = "postgresql" }

在polardb.toml中只配置差异部分：

# polardb.toml - 只配置与PostgreSQL不同的部分

[jdbc]
driverClass = "com.polardb.jdbc.Driver"
urlPrefix = "jdbc:polardb"
url = "jdbc:polardb://{host}:{port}/{databaseName}"

# 其他特定配置...

系统会自动从PostgreSQL配置中继承其他未定义的配置项。

系统影响

添加新的数据库方言配置会对系统产生以下影响：

1. 安装时可选数据库

如果在hetu.toml的[install]部分将新数据库配置为true（如示例中的polardb = true），则该数据库将出现在系统安装界面的可选数据库列表中。用户可以在安装系统时选择该数据库作为系统数据库。

[install]
mysql = true
postgresql = true
polardb = true  # 设置为true后，PolarDB将出现在安装选项中

2. 数据源可选数据库

添加新的数据库方言配置后，该数据库类型将出现在系统的"数据源管理"界面中，用户可以创建该类型的数据源连接。系统会根据hetu.toml中的[database]部分显示数据库名称和描述。

例如，添加PolarDB配置后，数据源类型下拉列表中将出现"PolarDB数据库"选项，其显示名称来自配置中的description属性。

[database]
polardb = { name = 'polardb', description = "PolarDB数据库" }  # "PolarDB数据库"将显示在数据源类型列表中

选择该数据源类型后，系统会根据对应的方言配置文件（如polardb.toml）生成连接表单和SQL语句，确保与该类型数据库的正确交互。

测试与验证

添加新的数据库方言配置后，应进行以下测试和验证：

连接测试：验证系统能否正确连接到该类型的数据库
元数据查询：验证系统能否正确获取数据库的元数据（表、列等）
SQL生成：验证系统能否生成符合该数据库语法的SQL语句
安装测试：测试对该数据库是否能正确安装

注意事项

确保JDBC驱动类在类路径中可用
验证元数据查询SQL在目标数据库中能够正确执行
测试数据类型映射是否正确
检查SQL模板是否符合目标数据库的语法
确保TOML文件名（不含后缀）与hetu.toml中的键名和name属性值完全一致