Skip to content

Commit 9217f1a

Browse files
hhunter-mshhunter-ms
authored
Merge pull request #3555 from ItalyPaleAle/fix-3344
Update SQL Server docs for Azure AD
2 parents 29898d2 + 01ac56c commit 9217f1a

File tree

1 file changed

+66
-32
lines changed
  • daprdocs/content/en/reference/components-reference/supported-state-stores

1 file changed

+66
-32
lines changed

‎daprdocs/content/en/reference/components-reference/supported-state-stores/setup-sqlserver.md

Lines changed: 66 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,16 @@
22
type: docs
33
title: "Microsoft SQL Server & Azure SQL"
44
linkTitle: "Microsoft SQL Server & Azure SQL"
5-
description: Detailed information on the Microsoft SQL Server and Azure SQL state store component
5+
description: Detailed information on the Microsoft SQL Server state store component
66
aliases:
77
- "/operations/components/setup-state-store/supported-state-stores/setup-sqlserver/"
88
---
99

1010
## Component format
1111

12-
To set up Microsoft SQL Server and Azure SQL state stores, create a component of type `state.sqlserver`. See [this guide]({{< ref "howto-get-save-state.md#step-1-setup-a-state-store" >}}) on how to create and apply a state store configuration.
12+
This state store component can be used with both [Microsoft SQL Server](https://learn.microsoft.com/sql/) and [Azure SQL](https://learn.microsoft.com/azure/azure-sql/).
13+
14+
To set up this state store, create a component of type `state.sqlserver`. See [this guide]({{< ref "howto-get-save-state.md#step-1-setup-a-state-store" >}}) on how to create and apply a state store configuration.
1315

1416

1517
```yaml
@@ -21,30 +23,42 @@ spec:
2123
type: state.sqlserver
2224
version: v1
2325
metadata:
24-
- name: connectionString
25-
value: <REPLACE-WITH-CONNECTION-STRING> # Required.
26-
- name: tableName
27-
value: <REPLACE-WITH-TABLE-NAME> # Optional. defaults to "state"
28-
- name: keyType
29-
value: <REPLACE-WITH-KEY-TYPE> # Optional. defaults to "string"
30-
- name: keyLength
31-
value: <KEY-LENGTH> # Optional. defaults to 200. You be used with "string" keyType
32-
- name: schema
33-
value: <SCHEMA> # Optional. defaults to "dbo"
34-
- name: indexedProperties
35-
value: <INDEXED-PROPERTIES> # Optional. List of IndexedProperties.
36-
- name: metadataTableName # Optional. Name of the table where to store metadata used by Dapr
37-
value: "dapr_metadata"
38-
- name: cleanupIntervalInSeconds # Optional. Cleanup interval in seconds, to remove expired rows
39-
value: 300
40-
26+
# Authenticate using SQL Server credentials
27+
- name: connectionString
28+
value: |
29+
Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;
30+
31+
# Authenticate with Azure AD (Azure SQL only)
32+
# "useAzureAD" be set to "true"
33+
- name: useAzureAD
34+
value: true
35+
# Connection string or URL of the Azure SQL database, optionally containing the database
36+
- name: connectionString
37+
value: |
38+
sqlserver://myServerName.database.windows.net:1433?database=myDataBase
39+
40+
# Other optional fields (listing default values)
41+
- name: tableName
42+
value: "state"
43+
- name: metadataTableName
44+
value: "dapr_metadata"
45+
- name: schema
46+
value: "dbo"
47+
- name: keyType
48+
value: "string"
49+
- name: keyLength
50+
value: "200"
51+
- name: indexedProperties
52+
value: ""
53+
- name: cleanupIntervalInSeconds
54+
value: "3600"
4155
```
4256
4357
{{% alert title="Warning" color="warning" %}}
4458
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
4559
{{% /alert %}}
4660
47-
If you wish to use SQL server as an [actor state store]({{< ref "state_api.md#configuring-state-store-for-actors" >}}), append the following to the yaml.
61+
If you wish to use SQL server as an [actor state store]({{< ref "state_api.md#configuring-state-store-for-actors" >}}), append the following to the metadata:
4862
4963
```yaml
5064
- name: actorStateStore
@@ -53,24 +67,43 @@ If you wish to use SQL server as an [actor state store]({{< ref "state_api.md#co
5367
5468
## Spec metadata fields
5569
70+
### Authenticate using SQL Server credentials
71+
72+
The following metadata options are **required** to authenticate using SQL Server credentials. This is supported on both SQL Server and Azure SQL.
73+
74+
| Field | Required | Details | Example |
75+
|--------|:--------:|---------|---------|
76+
| `connectionString` | Y | The connection string used to connect.<br>If the connection string contains the database, it must already exist. Otherwise, if the database is omitted, a default database named "Dapr" is created. | `"Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"` |
77+
78+
### Authenticate using Azure AD
79+
80+
Authenticating with Azure AD is supported with Azure SQL only. All authentication methods supported by Dapr can be used, including client credentials ("service principal") and Managed Identity.
81+
82+
| Field | Required | Details | Example |
83+
|--------|:--------:|---------|---------|
84+
| `useAzureAD` | Y | Must be set to `true` to enable the component to retrieve access tokens from Azure AD. | `"true"` |
85+
| `connectionString` | Y | The connection string or URL of the Azure SQL database, **without credentials**.<br>If the connection string contains the database, it must already exist. Otherwise, if the database is omitted, a default database named "Dapr" is created. | `"sqlserver://myServerName.database.windows.net:1433?database=myDataBase"` |
86+
| `azureTenantId` | N | ID of the Azure AD tenant | `"cd4b2887-304c-47e1-b4d5-65447fdd542b"` |
87+
| `azureClientId` | N | Client ID (application ID) | `"c7dd251f-811f-4ba2-a905-acd4d3f8f08b"` |
88+
| `azureClientSecret` | N | Client secret (application password) | `"Ecy3XG7zVZK3/vl/a2NSB+a1zXLa8RnMum/IgD0E"` |
89+
90+
### Other metadata options
91+
5692
| Field | Required | Details | Example |
5793
|--------------------|:--------:|---------|---------|
58-
| connectionString | Y | The connection string used to connect. If the connection string contains the database it must already exist. If the database is omitted a default database named `"Dapr"` is created. | `"Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"`
59-
| tableName | N | The name of the table to use. Alpha-numeric with underscores. Defaults to `"state"` | `"table_name"`
60-
| keyType | N | The type of key used. Defaults to `"string"` | `"string"`
61-
| keyLength | N | The max length of key. Used along with `"string"` keytype. Defaults to `"200"` | `"200"`
62-
| schema | N | The schema to use. Defaults to `"dbo"` | `"dapr"`,`"dbo"`
63-
| indexedProperties | N | List of IndexedProperties. | `'[{"column": "transactionid", "property": "id", "type": "int"}, {"column": "customerid", "property": "customer", "type": "nvarchar(100)"}]'`
64-
| actorStateStore | N | Indicates that Dapr should configure this component for the actor state store ([more information]({{< ref "state_api.md#configuring-state-store-for-actors" >}})). | `"true"`
65-
| metadataTableName | N | Name of the table Dapr uses to store a few metadata properties. Defaults to `dapr_metadata`. | `"dapr_metadata"`
66-
| cleanupIntervalInSeconds | N | Interval, in seconds, to clean up rows with an expired TTL. Default: `3600` (i.e. 1 hour). Setting this to values <=0 disables the periodic cleanup. | `1800`, `-1`
94+
| `tableName` | N | The name of the table to use. Alpha-numeric with underscores. Defaults to `"state"` | `"table_name"`
95+
| `metadataTableName` | N | Name of the table Dapr uses to store a few metadata properties. Defaults to `dapr_metadata`. | `"dapr_metadata"`
96+
| `keyType` | N | The type of key used. Supported values: `"string"` (default), `"uuid"`, `"integer"`.| `"string"`
97+
| `keyLength` | N | The max length of key. Ignored if "keyType" is not `string`. Defaults to `"200"` | `"200"`
98+
| `schema` | N | The schema to use. Defaults to `"dbo"` | `"dapr"`,`"dbo"`
99+
| `indexedProperties` | N | List of indexed properties, as a string containing a JSON document. | `'[{"column": "transactionid", "property": "id", "type": "int"}, {"column": "customerid", "property": "customer", "type": "nvarchar(100)"}]'`
100+
| `actorStateStore` | N | Indicates that Dapr should configure this component for the actor state store ([more information]({{< ref "state_api.md#configuring-state-store-for-actors" >}})). | `"true"`
101+
| `cleanupIntervalInSeconds` | N | Interval, in seconds, to clean up rows with an expired TTL. Default: `"3600"` (i.e. 1 hour). Setting this to values <=0 disables the periodic cleanup. | `"1800"`, `"-1"`
67102

68103

69104
## Create a Microsoft SQL Server/Azure SQL instance
70105

71-
[Follow the instructions](https://docs.microsoft.com/azure/azure-sql/database/single-database-create-quickstart?view=azuresql&tabs=azure-portal) from the Azure documentation on how to create a SQL database. The database must be created before Dapr consumes it.
72-
73-
> Note: Microsoft SQL Server/Azure SQL state store also supports SQL Server running on VMs and in Docker.**
106+
[Follow the instructions](https://docs.microsoft.com/azure/azure-sql/database/single-database-create-quickstart?view=azuresql&tabs=azure-portal) from the Azure documentation on how to create a SQL database. The database must be created before Dapr consumes it.
74107

75108
In order to setup SQL Server as a state store, you need the following properties:
76109

@@ -104,6 +137,7 @@ CREATE CLUSTERED INDEX expiredate_idx ON state(ExpireDate ASC)
104137
```
105138

106139
## Related links
140+
107141
- [Basic schema for a Dapr component]({{< ref component-schema >}})
108142
- Read [this guide]({{< ref "howto-get-save-state.md#step-2-save-and-retrieve-a-single-state" >}}) for instructions on configuring state store components
109143
- [State management building block]({{< ref state-management >}})

0 commit comments

Comments
 (0)