数据源

数据源是数据墙DBW 连接后端数据库的配置描述。每个配置文件必须至少包含一个 data-source 定义，告诉引擎如何连接到你的数据库。

配置项

数据源通过 JSON 配置中的 data-source 块定义，包含三个核心字段：

配置项	说明	示例
database-type	数据库类型	mssql、postgresql、mysql
connection-string	数据库连接字符串	@env('CONN_STR')
options	数据库特定选项	会话上下文等

推荐使用 @env('VAR_NAME') 语法引用环境变量中的连接字符串，避免在配置文件中硬编码密码。

配置示例

SQL Server

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost,1433;Database=MyDb;User Id=app;Password=P@ssw0rd;TrustServerCertificate=true;",
    "options": {
      "set-session-context": true
    }
  }
}

PostgreSQL

{
  "data-source": {
    "database-type": "postgresql",
    "connection-string": "Host=localhost;Port=5432;Database=MyDb;User ID=postgres;Password=P@ssw0rd;"
  }
}

MySQL

{
  "data-source": {
    "database-type": "mysql",
    "connection-string": "Server=localhost;Port=3306;Database=MyDb;User=root;Password=P@ssw0rd;"
  }
}

使用环境变量

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

启动服务前设置环境变量：

# Windows (PowerShell)
$env:SQL_CONNECTION_STRING = "Server=localhost;Database=MyDb;..."

# Linux / macOS
export SQL_CONNECTION_STRING="Server=localhost;Database=MyDb;..."

同一份配置文件在不同环境中只需修改环境变量值，无需改动配置本身。

支持的数据库

数据库	database-type 值	说明
SQL Server	mssql	支持表、视图、存储过程、自动实体发现
PostgreSQL	postgresql	支持表、视图、存储过程
MySQL	mysql	支持表、视图、存储过程

不同数据库在能力上存在细微差异，详情请参阅功能可用性。

多数据源

通过 data-source-files 字段可以引用额外的配置文件，每个文件定义各自的数据源和实体：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('MAIN_DB')"
  },
  "data-source-files": ["config-crm.json", "config-erp.json"]
}

实体和权限分散在各配置文件中定义，运行时配置集中在顶层文件。所有实体在同一个 API 入口下统一对外暴露。

数据源健康检查

可以为数据源配置健康检查，在运行时定期验证数据库连接的可用性：

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

健康检查结果可以通过 /health 端点查询，适用于容器编排平台的存活探测和监控系统集成。

连接弹性

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

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

该机制无需额外配置，引擎会在底层自动处理瞬时故障。