跳至主要內容

特定数据库方言配置

2025年7月7日大约 5 分钟

特定数据库方言配置

本文档详细介绍特定数据库方言配置文件（如mysql.toml、oracle.toml等）的结构和内容。

配置文件位置

特定数据库方言配置文件位于系统的以下目录：

/data/jdbc/

每种数据库方言对应一个独立的TOML格式配置文件，文件名为该数据库的标识符，如mysql.toml、oracle.toml等。

配置文件结构

特定数据库方言配置文件包含以下几个主要部分：

  1. 数据库版本配置
  2. JDBC连接配置
  3. JDBC URL属性
  4. 数据类型映射
  5. 元数据查询
  6. SQL模板
  7. 数据库特性
  8. 数据库函数映射
  9. 日期格式映射

1. 数据库版本配置

某些数据库（如Oracle）支持多个版本的配置，通过在配置文件顶部定义支持的版本列表：

# 支持的数据库版本列表
versions = [12, 11]

对于特定版本的配置，可以使用版本号作为前缀，例如：

# 版本11特有的JDBC配置
[11.jdbc]
url = "jdbc:oracle:thin:@{host}:{port}/{databaseName}"
calciteDialect = "org.apache.calcite.sql.HeTuOracle11Dialect"

# 版本11特有的SQL模板
[11.template]
limit = """SELECT * FROM ( SELECT TMP.*, ROWNUM ROW_ID FROM ( {sql} ) TMP WHERE ROWNUM <= ({offset} + {limit})) WHERE ROW_ID > {offset}"""

系统会根据连接的数据库版本自动选择对应的配置。如果某个版本没有特定配置，则使用默认配置。

2. JDBC连接配置 [jdbc]

这部分定义了与数据库建立连接所需的基本参数：

[jdbc]
driverClass = "com.mysql.cj.jdbc.Driver"   # JDBC驱动类
validationQuery = "SELECT 1"               # 连接验证查询
urlPrefix = "jdbc:mysql"                   # JDBC URL前缀
hibernateDialect = "org.hibernate.dialect.MySQLDialect"  # Hibernate方言类
calciteDialect = "org.apache.calcite.sql.dialect.HeTuMySqlDialect"  # Calcite方言类
url = "jdbc:mysql://{host}:{port}/{databaseName}"  # JDBC URL模板

属性说明：

  • driverClass：JDBC驱动类的全限定名
  • validationQuery：用于验证数据库连接是否有效的SQL查询
  • urlPrefix：JDBC URL的前缀
  • hibernateDialect：Hibernate ORM框架使用的方言类
  • calciteDialect：Calcite查询引擎使用的方言类
  • url：JDBC连接URL模板，其中的{host}、{port}、{databaseName}等占位符会在运行时被实际值替换

3. JDBC URL属性 [jdbc.urlProperties]

这部分定义了JDBC连接URL中的额外参数：

[jdbc.urlProperties]
useSSL = "false"
allowPublicKeyRetrieval = "false"
serverTimezone = "Asia/Shanghai"
characterEncoding = "utf-8"
rewriteBatchedStatements = "true"

这些属性会被添加到JDBC URL中，形如：jdbc:mysql://host:port/dbname?useSSL=false&serverTimezone=Asia/Shanghai

4. 数据类型映射 [type.XXX]

这部分定义了JDBC类型与数据库特定类型之间的映射关系：

[type.VARCHAR]
expr = "VARCHAR({length})"
length = { min = 0, max = 65535 }
id = 12
description = "字符串类型，最大长度65535"

[type.LONGVARCHAR]
expr = "longtext"
id = -1
length = { min = 0, max = 100000 }
description = "长字符串类型"

[type.INTEGER]
id = 4
expr = "INTEGER"
length = { min = 0, max = 2147483647 }
description = "整形"

属性说明：

  • expr：数据库特定的类型表达式，可包含{length}占位符
  • length：类型长度范围，包含min和max属性
  • id：对应的JDBC类型ID（来自java.sql.Types）
  • description：类型描述

5. 元数据查询 [metadata]

这部分定义了用于获取数据库元数据（如表、列信息等）的SQL查询：

[metadata]
schema = "SELECT DATABASE()"
catalog = "SELECT 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 UPPER(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 UPPER(TABLE_SCHEMA) = upper('{schema}') AND UPPER(TABLE_NAME)=UPPER('{tableName}')   
                 ORDER BY ORDINAL_POSITION ASC"""
# 查询所有表
tables = "SELECT table_name AS tableName, table_comment AS comment FROM information_schema.TABLES WHERE upper(table_schema) = upper('{schema}') AND table_type = 'BASE TABLE'"

属性说明：

  • schema：获取当前schema的SQL查询
  • catalog：获取当前catalog的SQL查询
  • column：获取表字段信息的SQL查询，包含字段名、类型、长度、精度、是否可空等信息
  • tables：获取所有表信息的SQL查询

这些查询中的{schema}、{catalog}、{tableName}等占位符会在运行时被实际值替换。

6. SQL模板 [template]

这部分定义了各种SQL操作的模板，用于生成特定数据库的SQL语句：

[template]
# 分页
limit = "{sql} LIMIT {limit} OFFSET {offset}"

# 表注释语句
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="
"}
>>"""

属性说明：

  • limit：分页查询模板
  • tableComment：表注释SQL模板
  • columnComment：列注释SQL模板
  • notNullExpr：非空约束表达式
  • defaultExpr：默认值表达式
  • addComment：是否添加注释
  • createTable：建表语句模板

这些模板使用StringTemplate模板引擎语法，可以包含条件判断和循环等逻辑。

7. 数据库特性 [characteristic]

这部分定义了数据库的特性和行为：

[characteristic]
# 支持隐式类型转换
implicitTypeConversion = true
# 字符串字面量的引号字符
literalQuote = "'"
# 标识符（如表名、列名等）的引用字符串
identifierQuote = "`"

属性说明：

  • implicitTypeConversion：是否支持隐式类型转换
  • literalQuote：字符串字面量使用的引号字符
  • identifierQuote：标识符（表名、列名等）使用的引用字符

8. 数据库函数映射 [function]

这部分定义了标准SQL函数到特定数据库函数的映射关系：

[function]
LENGTH = "LENGTH({str})"
CONCAT = "{str1}||{str2}||..."
SUBSTR = "SUBSTR({str}, {pos}, {len})"
SUBSTRING = "SUBSTR({str}, {pos}, {len})"
TRIM = "TRIM({str})"
DATE_FORMAT = "TO_CHAR({date}, {format})"
YEAR = "EXTRACT(YEAR FROM {date})"
QUARTER = "TO_CHAR({date}, 'Q')"
MONTH = "EXTRACT(MONTH FROM {date})"
WEEK = "TO_CHAR({date}, 'WW')"
DAY = "EXTRACT(DAY FROM {date})"
DATE_ADD.YEAR = "{date} + INTERVAL '{expr}' YEAR"
DATE_ADD.MONTH = "ADD_MONTHS({date}, {expr})"
DATE_ADD.DAY = "{date} + INTERVAL '{expr}' DAY"
TIMESTAMPDIFF.YEAR = "TRUNC(MONTHS_BETWEEN({datetime_expr2}, {datetime_expr1}) / 12)"
TIMESTAMPDIFF.MONTH = "MONTHS_BETWEEN({datetime_expr2}, {datetime_expr1})"
TIMESTAMPDIFF.DAY = "{datetime_expr2} - {datetime_expr1}"
CURDATE = "TRUNC(SYSDATE)"
CURTIME = "TO_CHAR(SYSDATE, 'HH24:MI:SS')"
NOW = "SYSDATE"
CEILING = "CEIL({X})"
RAND = "DBMS_RANDOM.VALUE"
SUM = "SUM({expr})"
AVG = "AVG({expr})"
COUNT = "COUNT({expr})"
MIN = "MIN({expr})"
MAX = "MAX({expr})"
MEDIAN = "MEDIAN({expr})"
STDDEV = "STDDEV({expr})"
VARIANCE = "VAR_POP({expr})"
IF = "CASE WHEN {expr1} THEN {expr2} ELSE {expr3} END"
NULLIF = "NULLIF({expr1}, {expr2})"
CAST.CHAR = "TO_CHAR({expr})"
CAST.INT = "TO_NUMBER({expr})"
CAST.DECIMAL = "TO_NUMBER({expr})"
STR_TO_DATE.DATE = "TO_DATE({str},{format})"
STR_TO_DATE.TIMESTAMP = "TO_TIMESTAMP({str},{format})"

属性说明：

  • 每个键值对表示一个函数映射，键是标准SQL函数名，值是数据库特定的函数实现
  • 函数参数使用花括号{}表示，如{str}、{date}等
  • 对于有子类型的函数（如DATE_ADD、CAST等），使用点号分隔，如DATE_ADD.YEAR

9. 日期格式映射 [format]

这部分定义了标准日期格式到数据库特定日期格式的映射：

[format]
YY = { expr = "YYYY" }
yy = { expr = "YY" }
Q = { expr = "Q" }
mm = { expr = "MM" }
U = { expr = "IW" }
d = { expr = "DD" }
H = { expr = "hh24" }
h = { expr = "hh" }
i = { expr = "mi" }
s = { expr = "ss" }

属性说明：

  • 每个键值对表示一个日期格式映射，键是标准格式，值是数据库特定的格式
  • expr：数据库特定的日期格式表达式
上次编辑于: 2025/7/10 14:38:02
贡献者: zhangshuaic