Add SQL Server state store documentation (#289)

Co-authored-by: Yaron Schneider <yaronsc@microsoft.com>

concepts/state-management/state-management.md

@@ -9,7 +9,7 @@ Dapr makes it simple for you to store key/value data in a store of your choice.
 Dapr brings reliable state management to applications through a simple state API. Developers can use this API to retrieve, save and delete states by keys.
 
 Dapr data stores are pluggable. Dapr ships with [Redis](https://redis.io
-) out-of-box. And it allows you to plug in other data stores such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB
+) out-of-box. And it allows you to plug in other data stores such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [SQL Server](https://azure.microsoft.com/services/sql-database/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB
 ), [GCP Cloud Spanner](https://cloud.google.com/spanner
 ) and [Cassandra](http://cassandra.apache.org/).
 
@@ -31,6 +31,7 @@ Store | Strong consistent write | Strong consistent read | ETag|
 Cosmos DB | Yes | Yes | Yes
 Redis | Yes | Yes | Yes
 Redis (clustered)| Yes | No | Yes
+SQL Server | Yes | Yes | Yes
 
 ## Concurrency
 Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the database.
@@ -83,6 +84,8 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE '<dapr-id>__delim__<thermometer>
 * [Spec: Dapr state management specification](../../reference/api/state.md)
 * [Spec: Dapr actors specification](../../reference/api/actors.md)
 * [How-to: Set up Azure Cosmos DB store](../../howto/setup-state-store/setup-azure-cosmosdb.md)
-* [How-to: Query Azure Cosmos DB store](../../howto/query-state-store/query-cosmosdb-store.md) 
+* [How-to: Query Azure Cosmos DB store](../../howto/query-state-store/query-cosmosdb-store.md)
 * [How-to: Set up Redis store](../../howto/setup-state-store/setup-redis.md)
-* [How-to: Query Redis store](../../howto/query-state-store/query-redis-store.md) 
+* [How-to: Query Redis store](../../howto/query-state-store/query-redis-store.md)
+* [How-to: Set up SQL Server store](../../howto/setup-state-store/setup-sqlserver.md)
+* [How-to: Query SQL Server store](../../howto/query-state-store/query-sqlserver-store.md)

howto/query-state-store/query-sqlserver-store.md

@@ -0,0 +1,59 @@
+# Query SQL Server state store
+
+Dapr doesn't transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see [Dapr state management spec](../../reference/api/state.md). You can directly interact with the underlying store to manipulate the state data, such querying states, creating aggregated views and making backups.
+
+## 1. Connect to SQL Server
+
+The easiest way to connect to your SQL Server instance is to use the [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) (Windows, macOS, Linux) or [SQL Server Management Studio](https://docs.microsoft.com/sql/ssms/download-sql-server-management-studio-ssms) (Windows).
+
+> **NOTE:** The following samples use Azure SQL. When you configure an Azure SQL database for Dapr, you need to specify the exact table name to use. The follow samples assume you've already connected to the right database with a table named "states".
+
+## 2. List keys by Dapr id
+
+To get all state keys associated with application "myapp", use the query:
+
+```sql
+SELECT * FROM states WHERE [Key] LIKE 'myapp-%'
+```
+
+The above query returns all rows with id containing "myapp-", which is the prefix of the state keys.
+
+## 3. Get specific state data
+
+To get the state data by a key "balance" for the application "myapp", use the query:
+
+```sql
+SELECT * FROM states WHERE [Key] = 'myapp-balance'
+```
+
+Then, read the **Data** field of the returned row.
+
+To get the state version/ETag, use the command:
+
+```sql
+SELECT [RowVersion] FROM states WHERE [Key] = 'myapp-balance'
+```
+
+## 4. Get filtered state data
+
+To get all state data where the value "color" in json data equals to "blue", use the query:
+
+```sql
+SELECT * FROM states WHERE JSON_VALUE([Data], '$.color') = 'blue'
+```
+
+## 5. Read actor state
+
+To get all the state keys associated with an actor with the instance ID "leroy" of actor type "cat" belonging to the application with ID "mypets", use the command:
+
+```sql
+SELECT * FROM states WHERE [Key] LIKE 'mypets-cat-leroy-%'
+```
+
+And to get a specific actor state such as "food", use the command:
+
+```sql
+SELECT * FROM states WHERE [Key] = 'mypets-cat-leroy-food'
+```
+
+> **WARNING:** You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime.

howto/setup-state-store/setup-sqlserver.md

@@ -0,0 +1,69 @@
+# Setup SQL Server
+
+## Creating an Azure SQL instance
+
+[Follow the instructions](https://docs.microsoft.com/azure/sql-database/sql-database-single-database-get-started?tabs=azure-portal) from the Azure documentation on how to create a SQL database.  The database must be created before Dapr consumes it.
+
+**Note: SQL Server state store also supports SQL Server running on  VMs.**
+
+In order to setup SQL Server as a state store, you will need the following properties:
+
+* **Connection String**: the SQL Server connection string. For example: server=localhost;user id=sa;password=your-password;port=1433;database=mydatabase;
+* **Schema**: The database schema do use (default=dbo). Will be created if not exists
+* **Table Name**: The database table name. Will be created if not exists
+* **Indexed Properties**: Optional properties from json data which will be indexed and persisted as individual column
+
+## Create a Dapr component
+
+The next step is to create a Dapr component for SQL Server.
+
+Create the following YAML file named `sqlserver.yaml`:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: <name>
+spec:
+  type: state.sqlserver
+  metadata:
+  - name: connectionString
+    value: <REPLACE-WITH-CONNECTION-STRING>
+  - name: tableName
+    value: <REPLACE-WITH-TABLE-NAME>
+```
+
+The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here](../../concepts/components/secrets.md)
+
+The following example uses the Kubernetes secret store to retrieve the secrets:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: <name>
+spec:
+  type: state.sqlserver
+  metadata:
+  - name: connectionString
+    secretKeyRef:
+      name: <KUBERNETES-SECRET-NAME>
+      key: <KUBERNETES-SECRET-KEY>
+  - name: tableName
+    value: <REPLACE-WITH-TABLE-NAME>
+```
+
+## Apply the configuration
+
+### In Kubernetes
+
+To apply the SQL Server state store to Kubernetes, use the `kubectl` CLI:
+
+```yaml
+kubectl apply -f sqlserver.yaml
+```
+
+### Running locally
+
+The Dapr CLI will automatically create a directory named `components` in your current working directory with a Redis component.
+To use SQL Server, replace the redis.yaml file with sqlserver.yaml file above.

howto/setup-state-store/supported-state-stores.md

@@ -12,3 +12,4 @@
 | Memcached | :white_check_mark: | :x: |
 | MongoDB | :white_check_mark: | :white_check_mark: |
 | Zookeeper | :white_check_mark: | :x: |
+| SQL Server  | :white_check_mark:  | :white_check_mark: |