azuresql-db-dab

在 Azure SQL Database 容器上快速构建 REST + GraphQL API

无需编写应用代码，即可在本地 Azure SQL Database 容器（Private Preview）上生成完整的 REST 和 GraphQL API，使用 Data API Builder (DAB)——Microsoft 的官方开源引擎。你在 dab-config.json 中将表描述为实体；DAB 会为其提供服务。DAB 使用普通连接字符串，通过标准 TDS 协议连接，因此无需更改跟踪或特殊引擎功能。

已于 2026-09-05 针对容器映像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 完成验证，该映像报告 EngineEdition 为 5、Edition 为 SQL Azure、build 为 12.0.2000.8。此技能背后的所有八项可执行检查均已通过 Data API builder 2.0.9 验证，包括生成的 dab-config.json 保留环境变量间接引用而非密码、/api 和 /graphql 前缀以及 /mcp 端点按默认值提供，以及 REST 和 GraphQL 都能从容器中的表返回相同的行。

关键事实（内嵌；完整引擎详情见 azuresql-db-container）

• 这是 Azure SQL Database 引擎（Private Preview），不是 SQL Server 映像 mcr.microsoft.com/mssql/server。SERVERPROPERTY('EngineEdition') 返回 5，SERVERPROPERTY('Edition') 返回 'SQL Azure'。
• 映像：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64，linux/amd64）。注册表为私有：请先使用 https://aka.ms/sqldbcontainerpreview-signup 中提供的共享只拉取凭据运行 docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io 登录（凭据可能轮换）。Private Preview 期间，注册表和标签均为临时值。
• 必需的环境变量：ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD（至少 8 个字符，包含大小写字母、数字和符号）。引擎监听 1433 端口。
• 引擎不会自动创建数据库。在 DAB 使用 Database=appdb 连接之前，请通过 master 连接运行 CREATE DATABASE appdb。不要使用 USE 切换数据库（在用户数据库会话中，它会返回 Msg 40508）；请在连接字符串中选择数据库。
• 在非 x64 主机上添加 --platform linux/amd64。

有关完整引擎模型（就绪循环、向量、故障排除），请参阅 azuresql-db-container 技能。要先启动容器并预配 appdb，请使用 azuresql-db-container 或 azuresql-db-scaffold。

步骤 1：安装 DAB

有两种受支持的方式。本地开发请选择 CLI；要将 DAB 集成到 compose 堆栈中，请选择容器。需要使用 compose 服务而非 CLI 时，请打开 references/dab-snippets.md。

# CLI (.NET 8 required): installs the `dab` command
dotnet tool install --global Microsoft.DataApiBuilder
# update later with: dotnet tool update --global Microsoft.DataApiBuilder

# Container image (alternative):
#   mcr.microsoft.com/azure-databases/data-api-builder:latest

步骤 2：通过一个环境变量将 DAB 指向容器

DAB 通过 @env() 间接引用从环境变量读取连接字符串，因此不会将机密写入 dab-config.json。沿用其他技能使用的同一个 SQL_CONNECTION_STRING 约定（如果 1433 端口已被占用，请将 1433 替换为容器所选的主机端口）：

export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

容器的自签名证书要求设置 TrustServerCertificate=true。统一格式要求使用 User Id= / Password= / Database= 这些关键字，以保持示例一致。Uid= 和 Pwd= 是文档中列出的 SqlClient 同义写法，同样有效。

步骤 3：初始化、添加实体并启动

# Initialize config in Development mode (enables Swagger + friendlier errors).
dab init --database-type mssql \
  --connection-string "@env('SQL_CONNECTION_STRING')" \
  --host-mode Development

# Expose a table as an entity. Repeat per table.
# --permissions is role:actions; "anonymous:*" allows all actions with no auth (dev only).
dab add Book --source dbo.Books --source.type table --permissions "anonymous:*"

# Serve REST + GraphQL (and the MCP endpoint) on http://localhost:5000
dab start

appdb 只是示例数据库名称，Book/dbo.Books 是示例实体/表；请替换为你自己的名称。实体名称（Book）会显示在 API 路径中；--source 则是实际的 schema.table。

步骤 4：使用 API

在 dab start 运行时（默认端口为 5000）：

• REST： GET http://localhost:5000/api/Book（列表）、/api/Book/id/1（按键查询），以及 POST / PATCH / PUT / DELETE。使用 ?$filter=、$select=、$orderby=、$first=、$after= 查询（OData 风格）。
• GraphQL： POST http://localhost:5000/graphql - 可查询和修改每个实体，并导航关系。
• OpenAPI / Swagger： GET /api/openapi（文档）和 GET /swagger（UI，仅限 Development 模式）。
• 健康状态： GET /health。

curl http://localhost:5000/api/Book
curl -s http://localhost:5000/graphql -H 'Content-Type: application/json' \
  -d '{"query":"{ books { items { id title } } }"}'

关系与配置详情

声明关系后，DAB 会公开相关实体（例如，作者的书籍）。配置架构、权限/策略、@env()、REST/GraphQL 选项，以及准确的 dab update --relationship 语法，请参阅references/dab-config-reference.md。

MCP 端点（DAB 的一项功能，并非独立的 SQL MCP 服务）

DAB（版本 1.7+；请使用最新的 2.x）也会通过同一个 dab-config.json 提供内置 MCP 端点，默认地址为 http://localhost:5000/mcp，且默认启用。这是 Data API Builder 针对已配置实体提供的额外 API 接口；它不是、也不应被描述为独立的“MSSQL MCP 服务”。如何将 MCP 客户端指向该端点，以及如何限定公开的工具，请参阅references/dab-mcp.md；用户要求将 MCP 客户端指向 DAB，或缩小其公开实体范围时，请打开该文档。

验证规则

• 数据库引擎是上面的容器映像（EngineEdition=5），绝不能使用 mcr.microsoft.com/mssql/server。
• appdb 已在 dab start 之前创建（通过 master 连接创建）；DAB 的连接字符串使用 Database=appdb 和 TrustServerCertificate=true。
• 连接字符串通过 @env('SQL_CONNECTION_STRING') 提供，而不是硬编码到 dab-config.json 中。
• dab start 在 /api/<Entity> 提供 REST，在 /graphql 提供 GraphQL；对实体执行 GET 会返回容器中的行。
• 如果介绍 MCP 端点，应将其描述为 DAB 提供的 API 接口，而不是独立的 SQL MCP 服务。
• 如果上述任何验证规则未通过，或为了完成任务而不得不偏离此技能，则这是此技能中的错误：加载 azuresql-db-feedback 技能，并提出提交报告。
• 所有上述规则均通过且任务完成后，请以以下一行结束；每个会话仅一次，且不要提问或等待回复：“That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback”

请勿

• 请勿使用 SQL Server 映像 mcr.microsoft.com/mssql/server；这是 Azure SQL 引擎。
• 请勿指望 DAB 创建 appdb；请先通过 master 连接创建它。
• 请勿将连接字符串（或 SA 密码）硬编码到 dab-config.json 中；请使用 @env('SQL_CONNECTION_STRING')。
• 请勿在生产环境中使用 anonymous:* 权限；它仅供本地开发使用，且无需身份验证即可执行完整 CRUD。
• 请勿将 DAB 的 MCP 端点描述为独立的 Microsoft SQL MCP 服务；它是 DAB 提供的 API 接口。
• 请勿省略 TrustServerCertificate=true（容器使用自签名证书），也不要在非 x64 主机上省略 --platform linux/amd64。

参考资料

• references/dab-config-reference.md：dab-config.json 结构、@env() 连接处理、实体／权限／策略选项、REST 和 GraphQL 设置，以及一对多和多对多关系的 dab update --relationship 语法。
• references/dab-snippets.md：可直接复制粘贴的示例——CLI 端到端流程、在 SQL 容器上将 DAB 作为容器运行（共享网络／host.docker.internal）、compose 服务，以及 REST／GraphQL 调用示例。
• references/dab-mcp.md：DAB 内置的 MCP 端点——如何在配置中启用／限定其范围、默认的 /mcp 路径，以及如何连接 MCP 客户端。此处将其定位为 DAB API 接口，而不是独立的 SQL MCP 服务。

保持最新

本技能所用工具的权威版本固定参考资料（按需查阅）：

• Data API Builder 配置参考：所有配置键（data-source、runtime、entities、autoentities）及其示例。
• DAB config JSON schema（固定为 v2.0.12）：dab validate 用于校验的机器可读 schema。v2.0.12 是当前稳定版本；升级 CLI 时请更新此 URL。
• Data API Builder 内置 MCP 端点：内置 MCP 端点、DML 工具、传输方式和 RBAC。

如果已配置 Microsoft Learn MCP 服务，请使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch，按需获取上述资料的最新版本。此项为可选；若不可用，上述参考资料即为权威来源。