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>
    }
  },
  "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>
    }
  }
}