配置文件结构

数据墙DBW 至少需要一个 JSON 配置文件才能运行。这个文件定义了数据库连接、要公开的实体、权限规则和运行时行为。所有配置集中在一个或多个 JSON 文件中，不依赖数据库、不生成代码、不产生二进制产物。

顶层字段

一个完整的配置文件包含以下顶层字段：

字段	必需	说明
$schema	是	JSON 架构引用，用于编辑器自动补全和校验
data-source	是	数据库连接信息
data-source-files	否	其他配置文件路径数组，用于多文件管理
runtime	否*	运行时行为配置（REST、GraphQL、MCP、缓存等）
entities	见说明	手动定义的实体列表。与 autoentities 二选一或共存
autoentities	见说明	按模式匹配自动发现实体。与 entities 二选一或共存

* runtime 仅在顶层配置文件中必需。在使用 data-source-files 的场景中，子文件的 runtime 会被忽略。

$schema 架构验证

每个配置文件以 $schema 开头，指定用于验证的 JSON Schema。编辑器（如 VS Code）会自动根据 Schema 提供字段补全和错误提示：

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json"
}

Schema 可以通过版本化 URL 锁定特定版本：

https://github.com/Azure/data-api-builder/releases/download/v1.0.0/dab.draft.schema.json

也可以使用相对路径引用本地下载的 Schema 文件：

{
  "$schema": "./dab.draft.schema.json"
}

没有 $schema 的配置文件仍然可以运行，但会失去编辑器的智能提示。

环境变量与密钥引用

配置文件中任何字符串值都可以使用 @env('变量名') 引用环境变量，避免在配置文件中写入明文密码：

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

引擎在加载配置时自动将 @env('VAR_NAME') 替换为环境变量的实际值。变量可来自系统环境变量或 .env 文件。详见环境变量与密钥。

最小可运行配置

一份最小可运行的配置文件只需要 $schema、data-source 和至少一个实体：

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONN_STRING')"
  },
  "entities": {
    "Book": {
      "source": { "object": "dbo.books", "type": "table" },
      "permissions": [
        { "role": "anonymous", "actions": ["read"] }
      ]
    }
  }
}

这份配置会生成 GET /api/Book 端点，允许匿名读取。不写 runtime 时使用默认值（REST 和 GraphQL 均启用）。

运行时默认值

如果省略 runtime 配置块，引擎使用以下默认行为：

设置	默认值
REST	启用，路径前缀 /api
GraphQL	启用，路径 /graphql，允许内省
MCP	启用（如运行时支持）
分页	默认 100 条，最大 100,000 条
主机模式	Production
缓存	关闭
日志	Warning 级别

开发阶段建议显式设置 "host": { "mode": "development" } 以启用 Swagger 和详细错误信息。

配置文件命名与位置

引擎默认查找当前目录下名为 dab-config.json 的文件。可以通过以下方式指定其他文件：

dab start --config ./settings/my-config.json

配合 DAB_ENVIRONMENT 环境变量，引擎会自动加载对应环境的配置文件（详见环境变量配置）。

下一步

• 配置数据源 — 数据库连接详解。
• 配置实体 — 实体字段和权限配置。
• 环境变量与密钥 — 安全地管理敏感信息。