Data source

The data-source section defines the database access details. It also defines database options.

Data source settings

Format overview

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      // mssql only
      "set-session-context": <true> (default) | <false>,
      // cosmosdb_nosql only
      "database": <string>,
      "container": <string>,
      "schema": <string>
    },
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    },
    "user-delegated-auth": {
      "enabled": <true> | <false> (default),
      "provider": <string>,
      "database-audience": <string>
    }
  },
  "data-source-files": ["<string>"]
}

Data source

Nested properties

Property values

Format

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    "options": {
      "<key-name>": <string>
    }
  }
}

Example: Azure SQL & SQL Server

"data-source": {
  "database-type": "mssql",
  "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=MyDatabase;User ID=MyUser;Password=MyPassword;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;",
    "options": {
      "set-session-context": true
    }
}

Consuming SESSION_CONTEXT

For Azure SQL and SQL Server, Data API builder can include Claims info in SQL's SESSION_CONTEXT.

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Use claims
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END

    SELECT Id, Name, Age, IsAdmin
    FROM Users
    WHERE Id = @userId;
END;

Example: Azure Cosmos DB

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "@env('SQL_CONNECTION_STRING')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

Environment variables

Use environment variables to keep plain text secrets out of your configuration file.

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

Connection resiliency

Data API builder uses Exponential Backoff to retry database requests after transient errors.

Managed Service Identities (MSI)

Managed Service Identities (MSI) are supported with DefaultAzureCredential defined in Azure.Identity library. Learn more about Managed identities in Microsoft Entra for Azure SQL.

User-Assigned Managed Identities (UAMI)

For User Assigned Managed Identity, append the Authentication and User ID properties to your connection string while substituting in your User Assigned Managed Identity's client ID: Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;.

System-Assigned Managed Identity (SAMI)

For System Assigned Managed Identity, append the Authentication property and exclude the UserId and Password arguments from your connection string: Authentication=Active Directory Managed Identity;.

Health (Data source)

Data API builder supports multiple configuration files, each with its own data source. This configuration block allows each data source to have its own health configuration.

Nested properties

Check name

Because multiple configuration files can point to data sources of the same type, those data sources can't be distinguished in the health report. Use name to assign a unique, identifiable label used only in the health report.

Check behavior

The simplest possible query—specific to the database type—is executed against the given data source to validate that the connection can be opened. Use the threshold-ms property to configure the maximum acceptable duration (in milliseconds) for that query to complete.

Format

{
  "data-source": {
    "health": {
      "enabled": <true> (default) | <false>,
      "name": <string>,
      "threshold-ms": <integer; default: 1000>
    }
  }
}

User-delegated auth

On-Behalf-Of (OBO) user-delegated authentication for SQL Server and Azure SQL. When enabled, DAB exchanges the incoming user token for a downstream SQL token so the database authenticates as the actual calling user. This feature is supported only for mssql data sources and requires Entra ID authentication upstream.

Nested properties

• enabled—turns OBO on or off.
• provider—the identity provider for the token exchange. Currently only EntraId is supported.
• database-audience—the target audience for the downstream SQL token (for example, https://database.windows.net).

Required environment variables

When OBO is enabled, DAB reads the following environment variables for the token exchange:

Per-user connection pooling

When OBO is enabled, DAB maintains separate SQL connection pools per user so that one user's access token is never reused for another user's request.

Format

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "user-delegated-auth": {
      "enabled": <true> | <false> (default),
      "provider": <string>,
      "database-audience": <string>
    }
  }
}

Example

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "user-delegated-auth": {
      "enabled": true,
      "provider": "EntraId",
      "database-audience": "https://database.windows.net"
    }
  }
}