数据库方言配置
数据库方言配置
本文档解答了关于数据库方言配置的常见问题，帮助您解决在配置过程中可能遇到的问题。
基础问题
数据库方言配置文件应该放在哪里？
数据库方言配置文件应放在系统的/data/jdbc/目录下。每个数据库方言对应一个独立的TOML格式配置文件，文件名应为该数据库的标识符，如mysql.toml、oracle.toml等。
修改配置文件后需要重启系统吗？
是的，修改数据库方言配置文件后需要重启系统才能生效。系统在启动时会加载所有数据库方言配置文件。
为什么数据库在数据源管理中不可见？
如果数据库在数据源管理界面的下拉列表中不可见，可能有以下原因：
hetu.toml文件中的[database]部分未包含该数据库的配置- 数据库方言配置文件（如
{database}.toml）不存在或命名不正确 - 配置文件中的键名与
name属性值不一致
确保在hetu.toml的[database]部分正确配置了数据库，并且配置文件存在且命名正确。
数据类型映射中的expr与{length}占位符是什么关系？
expr定义了数据库特定类型的表达式，可以包含{length}、{precision}和{scale}等占位符，这些占位符会在运行时被实际的值替换。
例如，对于VARCHAR类型：
[type.VARCHAR]
expr = "VARCHAR({length})"如果字段定义的长度为50，系统会将{length}替换为"50"，生成"VARCHAR(50)"作为最终的数据类型表达式。
如何设置数据库的继承关系？
在hetu.toml文件的[extend]部分设置数据库的继承关系：
[extend]
polardb = { type = "postgresql" } # 表示polardb继承postgresql的配置配置了继承关系后，新数据库（如polardb）会继承被继承数据库（如postgresql）的所有配置，只需在新数据库的配置文件中定义差异部分。
问题排查
数据库连接失败，如何排查？
如果数据库连接失败，请检查以下几点：
- JDBC驱动类是否正确加载（检查
driverClass配置） - JDBC URL格式是否正确（检查
url配置） - 连接参数（如用户名、密码、主机、端口等）是否正确
- 数据库服务是否正常运行
- 网络连接是否通畅（检查防火墙设置等）
您可以通过查看系统日志来获取更详细的错误信息。
为什么元数据查询失败？
元数据查询失败可能有以下原因：
- 元数据查询SQL语法不符合目标数据库的要求
- 查询返回的字段名与系统期望的名称不一致
- 用户权限不足，无法访问元数据表或视图
- 数据库版本不兼容
请根据目标数据库的特性调整元数据查询SQL，确保返回字段与系统要求一致。
表结构中的数据类型与预期不符怎么办？
如果生成的表结构中的数据类型与预期不符，请检查以下几点：
type.XXX配置是否正确expr表达式是否正确（特别是占位符的使用）- 字段长度、精度等参数是否在配置的范围内
- 是否有继承关系导致使用了被继承数据库的类型配置
修正相关配置后重新生成表结构。
为什么SQL语句执行失败？
SQL语句执行失败可能有以下原因：
- SQL模板不符合目标数据库的语法要求
- 标识符（如表名、列名）的引用字符不正确
- 字符串字面量的引号字符不正确
- 功能在目标数据库中不支持
请根据目标数据库的语法要求调整SQL模板，特别注意[characteristic]部分的配置，如identifierQuote和literalQuote。
高级问题
如何为特殊数据类型添加映射？
要为特殊数据类型添加映射，在数据库方言配置文件中添加相应的type.XXX配置：
[type.GEOMETRY]
id = 2004 # 对应的JDBC类型ID
expr = "GEOMETRY"
description = "空间几何类型"确保JDBC类型ID（id属性）与Java的java.sql.Types类定义的常量一致。
如何处理不同数据库的分页查询差异？
不同数据库的分页语法可能不同，您可以在各自的方言配置文件中定义不同的limit模板：
- MySQL/PostgreSQL：
"{sql} LIMIT {limit} OFFSET {offset}" - Oracle：
"SELECT * FROM (SELECT t.*, ROWNUM rn FROM ({sql}) t WHERE ROWNUM <= {limit}+{offset}) WHERE rn > {offset}" - SQL Server：
"WITH numbered_query AS (SELECT *, ROW_NUMBER() OVER (ORDER BY (SELECT 0)) AS row_num FROM ({sql}) t) SELECT * FROM numbered_query WHERE row_num > {offset} AND row_num <= {offset}+{limit}"
系统会根据目标数据库使用相应的分页模板。
如何处理SQL函数的方言差异？
对于SQL函数的方言差异，可以在各自的方言配置文件中的[function]部分定义不同的函数实现：
- MySQL：
TO_DATE = "STR_TO_DATE({expr}, {format})" - Oracle：
TO_DATE = "TO_DATE({expr}, {format})" - PostgreSQL：
TO_DATE = "TO_DATE({expr}, {format})"
系统会根据目标数据库使用相应的函数实现。
如何添加自定义函数？
要添加自定义函数，在数据库方言配置文件的[function]部分添加函数定义：
[function]
MY_CUSTOM_FUNCTION = "CUSTOM_FUNCTION({expr1}, {expr2})"然后在SQL中使用该函数：MY_CUSTOM_FUNCTION(field1, field2)，系统会自动转换为目标数据库的函数表达式。
其他问题
为什么推荐使用继承机制？
使用继承机制的主要优势：
- 减少重复配置：如果新数据库与现有数据库非常相似，则只需配置不同的部分
- 简化维护：当基础配置或被继承的配置更新时，所有继承它的配置自动获得更新
- 增强一致性：确保相似数据库之间的配置保持一致
- 减少出错可能：减少重复配置减少了出错的可能性
如何查看当前数据库实际使用的配置？
系统没有直接提供查看当前数据库实际使用配置的界面，但您可以通过以下方式了解：
- 查看对应的方言配置文件（如
mysql.toml） - 如果配置了继承关系，还需查看被继承的数据库配置文件（如
postgresql.toml） - 查看
hetu.toml中的基础配置
系统会按照优先级从高到低（特定数据库配置 > 被继承数据库配置 > 基础配置）应用这些配置。