Database-specific features reference for Data API builder

This reference covers features, behaviors, and requirements that are specific to one or more database platforms supported by Data API builder (DAB). For a cross-database feature comparison matrix, see Feature availability.

Database version support

DAB supports the following database platforms. Minimum version requirements apply to self-managed deployments. Platform-as-a-service (PaaS) databases don't have a minimum version requirement because the service manages the version.

SQL Server and Azure SQL

SESSION_CONTEXT

For SQL Server and Azure SQL, DAB can propagate authenticated user claims to the database by calling sp_set_session_context before executing each query. This mechanism lets SQL-native row-level security policies and stored procedures read the caller's identity from within the database engine.

When set-session-context is enabled in the DAB configuration, DAB sends all authenticated claims as key-value pairs:

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;

Common claims sent include roles, sub, oid, and any custom claims your identity provider includes in the JWT.

Enable SESSION_CONTEXT

Set --set-session-context true when calling dab init:

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

Or set the property directly in dab-config.json:

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

Use SESSION_CONTEXT in SQL

After enabling set-session-context, your SQL objects can read the claim values:

-- 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));

For a complete walkthrough, see Implement row-level security with session context.

SESSION_CONTEXT and connection pooling

DAB resets all session context values at the start of each request. However, because set-session-context forces per-user connection semantics, connection reuse across users is avoided automatically when this option is enabled.

Connection string variants

DAB uses Microsoft.Data.SqlClient for SQL Server and Azure SQL. The library supports these connection string formats.

Common formats:

Unsupported data types

The following SQL Server and Azure SQL data types aren't supported by DAB:

Azure Cosmos DB for NoSQL

Schema requirement

Unlike relational databases, Azure Cosmos DB for NoSQL is schema-agnostic. DAB can't introspect a Cosmos DB container to generate GraphQL types. You must provide a GraphQL schema file (.gql) that defines your document structure.

The schema file uses standard GraphQL Schema Definition Language (SDL) with two custom directives:

@model directive

The @model(name: "...") directive is required on every GraphQL type you expose through DAB. The name value must exactly match the entity name in your DAB configuration file.

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

@authorize directive

The @authorize directive provides field-level and type-level access control for Cosmos DB GraphQL queries. It accepts a roles parameter listing the roles that can access the field or type.

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

You can also apply @authorize at the type level:

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

For a complete setup guide, see Set up Data API builder for Azure Cosmos DB for NoSQL.

REST API unavailability

DAB doesn't generate REST endpoints for Azure Cosmos DB for NoSQL. Azure Cosmos DB provides a comprehensive native REST API for document operations. Only GraphQL endpoints are generated. OpenAPI documents aren't generated for Cosmos DB entities.

To access data over REST, use the Azure Cosmos DB REST API directly.

Unsupported features for Cosmos DB

The following features aren't supported for Azure Cosmos DB for NoSQL:

PostgreSQL

Minimum version

PostgreSQL 11 or later is required. DAB uses Npgsql as its PostgreSQL driver.

Unsupported data types

The following PostgreSQL data types aren't supported by DAB:

Stored procedures

Stored procedures aren't supported for PostgreSQL entities. Use tables and views instead.

MySQL

Minimum version

MySQL 8 or later is required.

Unsupported data types

The following MySQL data types aren't supported by DAB:

Stored procedures

Stored procedures aren't supported for MySQL entities. Use tables instead.

Azure Synapse Analytics (Dedicated SQL pool)

Supported objects

Dedicated SQL pool supports tables, views, and stored procedures—the same as SQL Server and Azure SQL. Serverless SQL pool isn't supported.

Unsupported features

Related content

• Feature availability
• Data source configuration reference
• Implement row-level security with session context
• Set up Data API builder for Azure Cosmos DB for NoSQL
• Release and versioning policies