数据 API 生成器的数据库特定功能参考

此参考涵盖了特定于数据 API 生成器支持的一个或多个数据库平台的功能、行为和要求。 有关跨数据库功能比较矩阵，请参阅 功能可用性。

数据库版本支持

DAB 支持以下数据库平台。 最低版本要求适用于自托管部署。 平台即服务（PaaS）数据库没有最低版本要求，因为该服务管理版本。

SQL Server 和 Azure SQL

SESSION_CONTEXT

对于 SQL Server 和 Azure SQL，DAB 可以在执行每个查询之前通过调用 sp_set_session_context 向数据库传播经过身份验证的用户声明。 此机制允许 SQL 本机行级安全策略和存储过程从数据库引擎中读取调用方标识。

在 DAB 配置中启用后 set-session-context ，DAB 会将所有经过身份验证的声明作为键值对发送：

EXEC sp_set_session_context 'roles', 'editor', @read_only = 0;
EXEC sp_set_session_context 'oid', 'a1b2c3d4-...', @read_only = 0;
-- Your query executes after claims are set
SELECT * FROM dbo.Documents;

发送的常见声明包括 roles、 sub标识 oid提供者包含在 JWT 中的任何自定义声明。

启用SESSION_CONTEXT

调用dab init时设置--set-session-context true：

dab init \
  --database-type mssql \
  --connection-string "@env('SQL_CONNECTION_STRING')" \
  --set-session-context true

或直接在 ： 中 dab-config.json设置属性：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  }
}

在 SQL 中使用SESSION_CONTEXT

启用 set-session-context后，SQL 对象可以读取声明值：

-- Read a claim in a stored procedure
DECLARE @role NVARCHAR(256) = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

-- Use a claim in a row-level security predicate function
CREATE FUNCTION dbo.RlsPredicate(@claimRole NVARCHAR(256))
RETURNS TABLE
WITH SCHEMABINDING
AS RETURN SELECT 1 AS result
WHERE @claimRole = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

有关完整演练，请参阅 使用会话上下文实现行级别安全性。

SESSION_CONTEXT和连接池

DAB 在每个请求开始时重置所有会话上下文值。 但是，由于 set-session-context 强制每用户连接语义，因此在启用此选项时，会自动避免跨用户重用连接。

连接字符串变体

DAB 用于 Microsoft.Data.SqlClient SQL Server 和 Azure SQL。 该库支持 这些连接字符串格式。

常见格式：

不支持的数据类型

DAB 不支持以下 SQL Server 和 Azure SQL 数据类型：

Azure Cosmos DB for NoSQL

架构要求

与关系数据库不同，Azure Cosmos DB for NoSQL 与架构无关。 DAB 无法反省 Cosmos DB 容器以生成 GraphQL 类型。 必须提供定义文档结构的 GraphQL 架构文件（.gql）。

架构文件使用标准 GraphQL 架构定义语言（SDL）和两个自定义指令：

@model 指令

在通过 DAB 公开的每个 GraphQL 类型上都需要该 @model(name: "...") 指令。 该值 name 必须与 DAB 配置文件中的实体名称完全匹配。

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
}

@authorize 指令

该 @authorize 指令为 Cosmos DB GraphQL 查询提供字段级和类型级访问控制。 它接受一个 roles 参数，其中列出了可以访问字段或类型的角色。

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "librarian"])
  internalNotes: String @authorize(roles: ["editor"])
}

还可以在类型级别应用 @authorize ：

type InternalReport @model(name: "InternalReport") @authorize(roles: ["auditor"]) {
  id: ID
  summary: String
}

有关完整的设置指南，请参阅 为 Azure Cosmos DB for NoSQL 设置数据 API 生成器。

REST API 不可用

DAB 不会为 Azure Cosmos DB for NoSQL 生成 REST 终结点。 Azure Cosmos DB 为文档操作提供全面的本机 REST API。 仅生成 GraphQL 终结点。 不会为 Cosmos DB 实体生成 OpenAPI 文档。

若要通过 REST 访问数据，请直接使用 Azure Cosmos DB REST API 。

Cosmos DB 不支持的功能

Azure Cosmos DB for NoSQL 不支持以下功能：

PostgreSQL

最低版本

需要 PostgreSQL 11 或更高版本。 DAB 用作 Npgsql 其 PostgreSQL 驱动程序。

不支持的数据类型

DAB 不支持以下 PostgreSQL 数据类型：

存储过程

PostgreSQL 实体不支持存储过程。 请改用表和视图。

MySQL

最低版本

需要 MySQL 8 或更高版本。

不支持的数据类型

DAB 不支持以下 MySQL 数据类型：

存储过程

MySQL 实体不支持存储过程。 请改用表。

Azure Synapse Analytics （专用 SQL 池）

支持的对象

专用 SQL 池支持表、视图和存储过程，与 SQL Server 和 Azure SQL 相同。 不支持无服务器 SQL 池。

不支持的功能

相关内容

• 功能可用性
• 数据源配置参考
• 使用会话上下文实现行级别安全性
• 为 Azure Cosmos DB for NoSQL 设置数据 API 生成器
• 发布和版本控制策略