Edit

Share via

Database connection configuration in Azure Static Web Apps (preview)

  • Article

Azure Static Web apps database connections work with various Azure databases.

As you connect a database to your static web app, you need to configure your database's firewall to accept network access from the Static Web Apps workers by allowing network access from Azure resources. Allowing specific Static Web Apps IP addresses isn't supported.

If you're using the Managed Identity authentication type, then you need to configure your static web app's Managed Identity profile to access your database.

Use this table for details about firewall and Managed Identity configuration for your database.

Name Type Firewall Managed Identity
Azure Cosmos DB Standard Configure firewall Configure Managed Identity
Azure SQL Standard Configure firewall Configure Managed Identity
Azure Database for MySQL Flex Configure firewall Not supported
Azure Database for PostgreSQL Flex Configure firewall Not supported
Azure Database for PostgreSQL (single) Single Configure firewall Configure Managed Identity

Configuration

You define the runtime behavior of the database connection in the staticwebapp.database.config.json file. Before you link a database to your static web app, you need to create this file within your repository. By convention, this file exists in the swa-db-connections folder at the root of your repository, but you can relocate it if you wish.

The purpose of the configuration file is to:

  • Map paths off the /data-api endpoint to your database tables or entities
  • Expose REST or GraphQL endpoints (or both)
  • Define entity security rules
  • Control development configuration settings

If you're using Azure Cosmos DB with GraphQL, you also need to provide a gql schema file.

Note

Static Web Apps database connections requires a folder containing the configuration files. This folder must contain the staticwebapp.database.config.json configuration file for all database types. For Cosmos DB for NoSQL databases, a staticwebapp.database.schema.gql schema file is also required.

By convention, this folder is named swa-db-connections and placed at the root of the repository. This convention can be overridden with a custom-configuration-folder.

Sample configuration file

The following sample configuration file shows you how to connect to an Azure SQL database and expose both REST and GraphQL endpoints. For full details on the configuration file and its supported features, refer to the Data API Builder documentation.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": false 
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/rest"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "production",
      "cors": {
        "origins": ["http://localhost:4280"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {
    "Person": {
      "source": "dbo.MyTestPersonTable",
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete"],
          "role": "anonymous"
        }
      ]
    }
  }
}
Property Description
$schema The version of the Database API builder used by Azure Static Web Apps to interpret the configuration file.
data-source Configuration settings specific to the target database. The database-type property accepts mssql, postgresql, cosmosdb_nosql, or mysql.

The connection string is overwritten upon deployment when a database is connected to your Static Web Apps resource. During local development, the connection string defined in the configuration file is what is used to connect to the database.
runtime Section that defines the exposed endpoints. The rest and graphql properties control the URL fragment used to access the respective API protocol. The host configuration section defines settings specific to your development environment. Make sure the origins array include your localhost address and port. The host.mode is overwritten to production when a database is connected to your Static Web Apps resource.
entities Section that maps URL path to database entities and tables. The same role-based authentication rules used to secure paths also secure database entities, and can be used to define permissions for each entity. The entities object also specifies the relationships between entities.

Generate configuration file

The Static Web Apps CLI allows you to generate a configuration file stub.

Important

To improve the security of deployments from the Static Web Apps CLI, a breaking change was introduced that requires you to upgrade to the latest version (2.0.2) of the Static Web Apps CLI by Jan. 15th, 2025.

Use the swa db init --database-type <YOUR_DATABASE_TYPE> to generate a configuration file. By default, the CLI creates a new staticwebapp.database.config.json in a folder named swa-db-connections.

Supported database types include:

  • mssql
  • postgresql
  • cosmosdb_nosql
  • mysql

Custom configuration folder

The default folder name for the staticwebapp.database.config.json file is swa-db-connections. If you'd like to use a different folder, you need to update your workflow file to tell the static web apps runtime where to find your configuration file. The data_api_location property allows you to define the location of your configuration folder.

Note

Folder that holds the staticwebapp.database.config.json file must be at the root of your static web apps repository.

The following code shows you how to use a folder named db-config for the database configuration file.

app_location: "/src"
api_location: "api"
output_location: "/dist"
data_api_location: "db-config" # Folder holding the staticwebapp.database.config.json file

Configure database connectivity

Azure Static Web Apps must have network access to your database for database connections to work. Additionally, to use an Azure database for local development, you need to configure your database to allow requests from your own IP address. The following are generic steps that apply to all databases. For specific steps for your database type, refer to the above links.

  • Go to your database in the Azure portal.
  • Go to the Networking tab.
  • Under the Firewall rules section, select Add your client IPv4 address. This step ensures that you can use this database for your local development.
  • Select the Allow Azure services and resources to access this server checkbox. This step ensures that your deployed Static Web Apps resource can access your database.
  • Select Save.

Connect a database

Linking a database to your static web app establishes the production connection between your website and database when published to Azure.

  1. Open your static web app in the Azure portal.

  2. In the Settings section, select Database connection.

  3. Under the Production section, select the Link existing database link.

  4. In the Link existing database window, enter the following values:

    Property Value
    Database Type Select your database type from the dropdown list.
    Subscription Select your Azure subscription from the dropdown list.
    Resource Name Select the database server name that has your desired database.
    Database Name Select the name of the database you want to link to your static web app.
    Authentication Type Select the connection type required to connect to your database.

Related content

Add a database to your static web app using one of the following databases:

Additionally, you can learn about how to use the Data API builder with Azure Static Web Apps.