Merge pull request #226739 from Charles-Gagnon/chgagnon/updateSqlBindingDocs

Update SQL binding docs

Author: v-regandowner

articles/azure-functions/functions-bindings-azure-sql-trigger.md

@@ -11,17 +11,36 @@ zone_pivot_groups: programming-languages-set-functions-lang-workers
 
 # Azure SQL trigger for Functions (preview)
 
+::: zone pivot="programming-language-csharp"
+
 > [!NOTE]
-> The Azure SQL trigger is only supported on **Premium and Dedicated** plans. Consumption is not supported.
+> The Azure SQL trigger is only supported on **Premium and Dedicated** plans. Consumption is not currently supported.
 
 The Azure SQL trigger uses [SQL change tracking](/sql/relational-databases/track-changes/about-change-tracking-sql-server) functionality to monitor a SQL table for changes and trigger a function when a row is created, updated, or deleted.
 
 For configuration details for change tracking for use with the Azure SQL trigger, see [Set up change tracking](#set-up-change-tracking-required). For information on setup details of the Azure SQL extension for Azure Functions, see the [SQL binding overview](./functions-bindings-azure-sql.md).
 
-## Example usage
-<a id="example"></a>
+## Functionality Overview
 
-::: zone pivot="programming-language-csharp"
+The Azure SQL Trigger binding uses a polling loop to check for changes, triggering the user function when changes are detected. At a high level the loop looks like this:
+
+```
+while (true) {
+    1. Get list of changes on table - up to a maximum number controlled by the Sql_Trigger_MaxBatchSize setting
+    2. Trigger function with list of changes
+    3. Wait for delay controlled by Sql_Trigger_PollingIntervalMs setting
+}
+```
+
+Changes will always be processed in the order that their changes were made, with the oldest changes being processed first. A couple notes about this:
+
+1. If changes to multiple rows are made at once the exact order that they'll be sent to the function is based on the order returned by the CHANGETABLE function
+2. Changes are "batched" together for a row - if multiple changes are made to a row between each iteration of the loop then only a single change entry will exist for that row that shows the difference between the last processed state and the current state
+3. If changes are made to a set of rows, and then another set of changes are made to half of those same rows then the half that wasn't changed a second time will be processed first. This is due to the above note with the changes being batched - the trigger will only see the "last" change made and use that for the order it processes them in
+
+See [Work with change tracking](/sql/relational-databases/track-changes/work-with-change-tracking-sql-server) for more information on change tracking and how it's used by applications such as Azure SQL triggers.
+
+## Example usage
 
 More samples for the Azure SQL trigger are available in the [GitHub repository](https://github.com/Azure/azure-functions-sql-extension/tree/main/samples/samples-csharp).
 
@@ -88,48 +107,30 @@ Isolated worker process isn't currently supported.
 -->
 ---
 
-
-::: zone-end
-
-::: zone pivot="programming-language-java,programming-language-powershell,programming-language-javascript,programming-language-python"
-
-> [!NOTE]
-> In the current preview, Azure SQL triggers are only supported by [C# class library functions](functions-dotnet-class-library.md)
-
-::: zone-end
-
-
-::: zone pivot="programming-language-csharp"
-## Attributes 
+## Attributes
 
 The [C# library](functions-dotnet-class-library.md) uses the [SqlTrigger](https://github.com/Azure/azure-functions-sql-extension/blob/main/src/TriggerBinding/SqlTriggerAttribute.cs) attribute to declare the SQL trigger on the function, which has the following properties:
 
 | Attribute property |Description|
 |---------|---------|
 | **TableName** | Required. The name of the table being monitored by the trigger.  |
-| **ConnectionStringSetting** | Required. The name of an app setting that contains the connection string for the database which contains the table being monitored for changes. The connection string setting name corresponds to the application setting (in `local.settings.json` for local development) that contains the [connection string](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-5.&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString) to the Azure SQL or SQL Server instance.| 
-
-
-::: zone-end
+| **ConnectionStringSetting** | Required. The name of an app setting that contains the connection string for the database which contains the table being monitored for changes. The connection string setting name corresponds to the application setting (in `local.settings.json` for local development) that contains the [connection string](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-5.&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString) to the Azure SQL or SQL Server instance.|
 
 ## Configuration
 
 <!-- ### for another day ###
-::: zone pivot="programming-language-java,programming-language-powershell,programming-language-javascript,programming-language-python"  
-
 
 The following table explains the binding configuration properties that you set in the function.json file.
 
 |function.json property | Description|
 
-::: zone-end -->
-
+-->
 
 In addition to the required ConnectionStringSetting [application setting](./functions-how-to-use-azure-function-app-settings.md#settings), the following optional settings can be configured for the SQL trigger:
 
 | App Setting | Description|
 |---------|---------|
-|**Sql_Trigger_BatchSize** |This controls the number of changes processed at once before being sent to the triggered function. The default value is 100.|
+|**Sql_Trigger_BatchSize** |This controls the maximum number of changes processed with each iteration of the trigger loop before being sent to the triggered function. The default value is 100.|
 |**Sql_Trigger_PollingIntervalMs**|This controls the delay in milliseconds between processing each batch of changes. The default value is 1000 (1 second).|
 |**Sql_Trigger_MaxChangesPerWorker**|This controls the upper limit on the number of pending changes in the user table that are allowed per application-worker. If the count of changes exceeds this limit, it may result in a scale out. The setting only applies for Azure Function Apps with [runtime driven scaling enabled](#enable-runtime-driven-scaling). The default value is 1000.|
 
@@ -138,7 +139,7 @@ In addition to the required ConnectionStringSetting [application setting](./func
 
 ## Set up change tracking (required)
 
-Setting up change tracking for use with the Azure SQL trigger requires two steps.  These steps can be completed from any SQL tool that supports running queries, including [VS Code](/sql/tools/visual-studio-code/mssql-extensions), [Azure Data Studio](/sql/azure-data-studio/download-azure-data-studio) or [SQL Server Management Studio](/sql/ssms/download-sql-server-management-studio-ssms).
+Setting up change tracking for use with the Azure SQL trigger requires two steps.  These steps can be completed from any SQL tool that supports running queries, including [Visual Studio Code](/sql/tools/visual-studio-code/mssql-extensions), [Azure Data Studio](/sql/azure-data-studio/download-azure-data-studio) or [SQL Server Management Studio](/sql/ssms/download-sql-server-management-studio-ssms).
 
 1. Enable change tracking on the SQL database, substituting `your database name` with the name of the database where the table to be monitored is located:
 
@@ -166,12 +167,21 @@ Setting up change tracking for use with the Azure SQL trigger requires two steps
 
 ## Enable runtime-driven scaling
 
-Optionally, your functions can scale automatically based on the amount of changes that are pending to be processed in the user table. To allow your functions to scale properly on the Premium plan when using SQL triggers, you need to enable runtime scale monitoring.
+Optionally, your functions can scale automatically based on the number of changes that are pending to be processed in the user table. To allow your functions to scale properly on the Premium plan when using SQL triggers, you need to enable runtime scale monitoring.
 
 [!INCLUDE [functions-runtime-scaling](../../includes/functions-runtime-scaling.md)]
 
 
 ## Next steps
 
 - [Read data from a database (Input binding)](./functions-bindings-azure-sql-input.md)
-- [Save data to a database (Output binding)](./functions-bindings-azure-sql-output.md)
+- [Save data to a database (Output binding)](./functions-bindings-azure-sql-output.md)
+
+::: zone-end
+
+::: zone pivot="programming-language-java,programming-language-powershell,programming-language-javascript,programming-language-python"
+
+> [!NOTE]
+> In the current preview, Azure SQL triggers are only supported by [C# class library functions](functions-dotnet-class-library.md)
+
+::: zone-end

articles/azure-functions/functions-bindings-azure-sql.md

@@ -27,7 +27,7 @@ This set of articles explains how to work with [Azure SQL](/azure/azure-sql/inde
 
 ## Install extension
 
-The extension NuGet package you install depends on the C# mode you're using in your function app: 
+The extension NuGet package you install depends on the C# mode you're using in your function app:
 
 # [In-process](#tab/in-process)
 
@@ -59,15 +59,15 @@ You can install this version of the extension in your function app by registerin
 
 ---
 
-::: zone-end 
+::: zone-end
 
 
 ::: zone pivot="programming-language-javascript, programming-language-powershell"
 
 
-## Install bundle    
+## Install bundle
 
-The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.  
+The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.
 
 
 # [Preview Bundle v4.x](#tab/extensionv4)
@@ -93,7 +93,7 @@ Azure SQL bindings for Azure Functions aren't available for the v3 version of th
 ::: zone-end
 
 
-::: zone pivot="programming-language-python"  
+::: zone pivot="programming-language-python"
 
 ## Functions runtime
 
@@ -103,7 +103,7 @@ Azure SQL bindings for Azure Functions aren't available for the v3 version of th
 
 ## Install bundle
 
-The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.  
+The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.
 
 # [Preview Bundle v4.x](#tab/extensionv4)
 
@@ -125,15 +125,9 @@ Azure SQL bindings for Azure Functions aren't available for the v3 version of th
 
 ---
 
-## Update packages
-
-Support for the SQL bindings extension is available in the 1.11.3b1 version of the [Azure Functions Python library](https://pypi.org/project/azure-functions/).  Add this version of the library to your functions project with an update to the line for `azure-functions==` in the `requirements.txt` file in your Python Azure Functions project as seen in the following snippet:
-
-```
-azure-functions==1.11.3b1
-```
+## Configure Python Worker
 
-Following setting the library version, update your application settings to [isolate the dependencies](./functions-app-settings.md#python_isolate_worker_dependencies) by adding `PYTHON_ISOLATE_WORKER_DEPENDENCIES` with the value `1` to your application settings.  Locally, this is set in the `local.settings.json` file as seen below:
+Currently, you will need to update your application settings to [isolate the dependencies](./functions-app-settings.md#python_isolate_worker_dependencies) by adding `PYTHON_ISOLATE_WORKER_DEPENDENCIES` with the value `1` to your application settings. Locally, this is set in the `local.settings.json` file as seen below:
 
 ```json
 "PYTHON_ISOLATE_WORKER_DEPENDENCIES": "1"
@@ -145,12 +139,12 @@ Support for Python durable functions with SQL bindings isn't yet available.
 ::: zone-end
 
 
-::: zone pivot="programming-language-java"  
+::: zone pivot="programming-language-java"
 
 
 ## Install bundle
 
-The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.  
+The SQL bindings extension is part of a preview [extension bundle], which is specified in your host.json project file.
 
 # [Preview Bundle v4.x](#tab/extensionv4)
 
@@ -188,7 +182,7 @@ Add the Java library for SQL bindings to your functions project with an update t
 
 ## SQL connection string
 
-Azure SQL bindings for Azure Functions have a required property for connection string on both [input](./functions-bindings-azure-sql-input.md) and [output](./functions-bindings-azure-sql-output.md) bindings. SQL bindings passes the connection string to the Microsoft.Data.SqlClient library and supports the connection string as defined in the [SqlClient ConnectionString documentation](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-5.0&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString).  Notable keywords include:
+Azure SQL bindings for Azure Functions have a required property for the connection string on all bindings and triggers. These pass the connection string to the Microsoft.Data.SqlClient library and supports the connection string as defined in the [SqlClient ConnectionString documentation](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-5.0&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString).  Notable keywords include:
 
 - `Authentication` allows a function to connect to Azure SQL with Azure Active Directory, including [Active Directory Managed Identity](./functions-identity-access-azure-sql-with-managed-identity.md)
 - `Command Timeout` allows a function to wait for specified amount of time in seconds before terminating a query (default 30 seconds)