数据库连接配置

数据库连接配置是整个数据墙DBW 服务的基础。data-source 配置块定义了引擎如何与后端数据库建立连接、管理连接池和验证可用性。正确的连接配置直接影响 API 的性能、稳定性和安全性。

基本配置结构

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    },
    "health": {
      "enabled": true,
      "name": "main-db",
      "threshold-ms": 1000
    }
  }
}

数据库类型

值	数据库	驱动
mssql	SQL Server 2016+	Microsoft.Data.SqlClient
postgresql	PostgreSQL 11+	Npgsql
mysql	MySQL 8+	MySqlConnector

数据库类型决定了引擎使用的 ADO.NET 驱动以及可用的连接字符串参数和功能特性。

连接字符串

安全原则

连接字符串中通常包含密码等敏感信息，永远不要将明文连接字符串写入配置文件并提交版本控制。使用 @env() 引用环境变量：

{
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

SQL Server 连接字符串

Server=host,port;Database=db;User Id=user;Password=pwd;TrustServerCertificate=true;Encrypt=true;

核心参数：

参数	说明	建议
Server	主机地址和端口（逗号分隔）	生产环境使用 FQDN
Database	数据库名称	—
User Id / Password	SQL Server 认证凭据	或使用 Trusted_Connection=True 走 Windows 集成认证
TrustServerCertificate	跳过证书链验证	开发环境设为 true，生产用正式证书
Encrypt	启用传输加密	生产环境强烈建议 true
MultipleActiveResultSets	启用 MARS	使用 GraphQL 多重变更时必须为 true
Connection Timeout	建立连接的超时（秒）	默认 15 秒
Command Timeout	命令执行超时（秒）	默认 30 秒，大查询适当调高
Pooling	启用连接池	默认 true，对性能至关重要
Max Pool Size	连接池最大连接数	默认 100，高并发时适当调高

NOTE

Connection Timeout 控制建立数据库连接的等待时间，Command Timeout 控制 SQL 命令执行的等待时间。两者独立配置。

PostgreSQL 连接字符串

Host=host;Port=5432;Database=db;User ID=user;Password=pwd;CommandTimeout=30

核心参数：

参数	说明
Host / Port	主机和端口（冒号分隔）
Database	数据库名称
User ID / Password	认证凭据
CommandTimeout	命令超时（秒），默认 30
Connection Timeout	连接建立超时（秒），默认 15
Pooling	连接池，默认 true
Max Pool Size	最大连接数，默认 100
SSL Mode	SSL 模式：Disable/Prefer/Require

NOTE

PostgreSQL 驱动中字段名使用空格加 PascalCase（User ID、SSL Mode），与 SQL Server 和 MySQL 不同。

MySQL 连接字符串

Server=host;Port=3306;Database=db;User=user;Password=pwd;DefaultCommandTimeout=30

核心参数：

参数	说明
Server / Port	主机和端口
Database	数据库名称
User / Password	认证凭据
DefaultCommandTimeout	命令超时（秒），默认 30
Connection Timeout	连接建立超时（秒），默认 15
SslMode	SSL 模式：None/Preferred/Required

连接池管理

数据墙DBW 依赖 ADO.NET 的连接池来复用数据库连接。如果你在连接字符串中没有显式配置连接池参数，驱动使用默认值（通常为启用状态，最大 100 个连接）。

高并发场景建议

场景	建议 Max Pool Size
低流量（< 10 req/s）	默认 100，无需调整
中等流量（10–50 req/s）	100–200
高流量（> 50 req/s）	200–500
水平扩展（多实例）	每个实例适当降低，总连接数不超出数据库上限

可以通过监控数据库的活跃连接数来判断是否需要调整。连接池耗尽的表现是请求排队并最终超时。

options 选项

set-session-context（仅 SQL Server）

{
  "options": {
    "set-session-context": true
  }
}

启用后，数据墙DBW 在每次请求时将 JWT 令牌中的声明写入 SQL Server 的 SESSION_CONTEXT。数据库中的策略、存储过程或触发器可以通过 SESSION_CONTEXT(N'key') 读取调用方声明。

声明与 SESSION_CONTEXT 键的映射：

• userId 声明 → SESSION_CONTEXT(N'user.userid')
• roles 声明 → SESSION_CONTEXT(N'user.roles')
• 其他声明 → SESSION_CONTEXT(N'<type>')

默认值为 false。开启后需要注意：因为不同用户的会话上下文不同，缓存结果不能在不同用户间共享。

连接弹性

数据墙DBW 在遇到瞬时数据库连接错误时，会自动使用指数退避（Exponential Backoff）策略重试请求：

尝试次数	第一次	第二次	第三次	第四次	第五次
等待时间	2s	4s	8s	16s	32s

重试仅在瞬时错误（如网络抖动、连接池暂时耗尽）时触发。如果达到最大重试次数仍失败，请求将返回错误。此行为是引擎内置的，无需额外配置。

数据源健康检查

为数据源配置独立于实体的健康检查：

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "main-db",
      "threshold-ms": 1000
    }
  }
}

字段	说明	默认值
enabled	是否启用	true
name	在 /health 响应中的标识符	使用 database-type 值（如 mssql）
threshold-ms	查询超时阈值（毫秒），超时判定为降级	1000

数据源健康检查执行一条简单查询（如 SELECT 1），验证连接可用且响应在阈值内。

多数据源

详见多配置文件管理。

下一步

• 查询超时配置 — 控制数据库操作的最大执行时间。
• 配置数据源 — 配置字段参考。