Data source

data-source 节定义数据库访问详细信息，同时也定义数据库选项。

Data source 设置

属性	说明
data-source	包含数据库连接设置的对象
data-source.database-type	后端所用数据库：mssql、postgresql、mysql
data-source.connection-string	所选数据库类型的连接字符串
data-source.options	数据库特定属性
data-source.options.set-session-context	启用将 JSON Web Token (JWT) 声明作为会话上下文发送（仅 SQL Server）
data-source.health	配置数据源运行状况检查的对象
data-source.health.enabled	启用运行状况检查终结点
data-source.health.name	运行状况报告中使用的标识符
data-source.health.threshold-ms	运行状况检查查询允许的最大持续时间（毫秒）

格式概览

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    }
  },
  "data-source-files": ["<string>"]
}

Data source

Parent	Property	Type	Required	Default
$root	data-source	object	✔️ Yes	-

嵌套属性

Parent	Property	Type	Required	Default
data-source	database-type	enum	✔️ Yes	None
data-source	connection-string	string	✔️ Yes	None
data-source	options	object	❌ No	None

属性值

database-type	说明	最低版本
mssql	SQL Server	2016
postgresql	PostgreSQL	11
mysql	MySQL	8

格式

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      "<key-name>": <string>
    }
  }
}

示例：SQL Server

"data-source": {
  "database-type": "mssql",
  "connection-string": "Server=localhost,1433;Initial Catalog=MyDatabase;User ID=MyUser;Password=MyPassword;Encrypt=True;TrustServerCertificate=True;Connection Timeout=30;",
  "options": {
    "set-session-context": true
  }
}

NOTE

对于 SQL Server，数据墙DBW 使用 SqlClient。不同连接字符串变体的兼容性由该驱动决定。

使用 SESSION_CONTEXT

对于 SQL Server，数据墙DBW 可以将声明信息包含在 SQL 的 SESSION_CONTEXT 中。

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Use claims
    IF SESSION_CONTEXT(N'user_role') = 'admin'
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END

    SELECT Id, Name, Age, IsAdmin
    FROM Users
    WHERE Id = @userId;
END;

环境变量

使用环境变量可避免在配置文件中保存明文机密。

TIP

数据墙DBW 支持 @env() 函数，也支持 .env 文件。

"data-source": {
  "database-type": "mssql",
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

连接弹性

数据墙DBW 在遇到瞬时错误后，会使用指数退避（Exponential Backoff）重试数据库请求。

尝试次数	第一次	第二次	第三次	第四次	第五次
秒数	2s	4s	8s	16s	32s

Health (Data source)

Parent	Property	Type	Required	Default
data-source	health	object	No	-

数据墙DBW 支持多个配置文件，每个配置文件都可以指向独立数据源。该配置块允许为每个数据源分别设置健康检查。

嵌套属性

Parent	Property	Type	Required	Default
data-source.health	enabled	boolean	No	true
data-source.health	name	string	No	database-type
data-source.health	threshold-ms	integer	No	1000

检查名称

由于多个配置文件可能指向同一类型的数据源，因此这些数据源在健康报告中可能难以区分。使用 name 可以分配一个仅用于健康报告的唯一标识标签。

检查行为

系统会针对给定数据源执行该数据库类型下最简单的查询，以验证连接是否可打开。使用 threshold-ms 可配置该查询允许完成的最大时长（毫秒）。

格式

{
  "data-source": {
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    }
  }
}