Microsoft.Data.Sqlite: Document deferred transactions (#20507)

Resolves #20266

Author: bricelam

docs/standard/data/sqlite/transactions.md

@@ -1,6 +1,6 @@
 ---
 title: Transactions
-ms.date: 12/13/2019
+ms.date: 09/08/2020
 description: Learn how to use transactions.
 ---
 # Transactions
@@ -30,3 +30,12 @@ Microsoft.Data.Sqlite treats the IsolationLevel passed to <xref:Microsoft.Data.S
 The following code simulates a dirty read. Note, the connection string must include `Cache=Shared`.
 
 [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/DirtyReadSample/Program.cs?name=snippet_DirtyRead)]
+
+## Deferred transactions
+
+Starting with Microsoft.Data.Sqlite version 5.0, transactions can be deferred. This defers the creation of the actual transaction in the database until the first command is executed. It also causes the transaction to gradually upgrade from a read transaction to a write transaction as needed by its commands. This can be useful for enabling concurrent access to the database during the transaction.
+
+[!code-csharp[](../../../../samples/snippets/standard/data/sqlite/DeferredTransactionSample/Program.cs?name=snippet_DeferredTransaction)]
+
+> [!WARNING]
+> Commands inside a deferred transaction can fail if they cause the transaction to be upgraded from a read transaction to a write transaction while the database is locked. When this happens, the application will need to retry the entire transaction.

samples/snippets/standard/data/sqlite/DeferredTransactionSample/DeferredTransactionSample.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Data.Sqlite" Version="5.0.0-rc.1.20451.13" />
+  </ItemGroup>
+
+</Project>

samples/snippets/standard/data/sqlite/DeferredTransactionSample/Program.cs

@@ -0,0 +1,63 @@
+using System.IO;
+using Microsoft.Data.Sqlite;
+
+namespace DeferredTransactionSample
+{
+    class Program
+    {
+        static void Main()
+        {
+            var connection = new SqliteConnection("Data Source=DeferredTransactionSample.db");
+            connection.Open();
+
+            var createCommand = connection.CreateCommand();
+            createCommand.CommandText =
+            @"
+                CREATE TABLE data (
+                    value INTEGER
+                );
+
+                INSERT INTO data
+                VALUES (1);
+            ";
+            createCommand.ExecuteNonQuery();
+
+            #region snippet_DeferredTransaction
+            using (var transaction = connection.BeginTransaction(deferred: true))
+            {
+                // Before the first statement of the transaction is executed, both concurrent
+                // reads and writes are allowed
+
+                var readCommand = connection.CreateCommand();
+                readCommand.CommandText =
+                @"
+                    SELECT *
+                    FROM data
+                ";
+                var value = (long)readCommand.ExecuteScalar();
+
+                // After a the first read statement, concurrent writes are blocked until the
+                // transaction completes. Concurrent reads are still allowed
+
+                var writeCommand = connection.CreateCommand();
+                writeCommand.CommandText =
+                @"
+                    UPDATE data
+                    SET value = $newValue
+                ";
+                writeCommand.Parameters.AddWithValue("$newValue", value + 1L);
+                writeCommand.ExecuteNonQuery();
+
+                // After the first write statment, both concurrent reads and writes are blocked
+                // until the transaction completes
+
+                transaction.Commit();
+            }
+            #endregion
+
+            // Clean up
+            connection.Close();
+            File.Delete("DeferredTransactionSample.db");
+        }
+    }
+}

samples/snippets/standard/data/sqlite/Microsoft.Data.Sqlite.sln

@@ -43,6 +43,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DapperSample", "DapperSampl
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SqliteProviderSample", "SqliteProviderSample\SqliteProviderSample.csproj", "{E52BF2F4-6941-493F-8022-CD783889C1E2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DeferredTransactionSample", "DeferredTransactionSample\DeferredTransactionSample.csproj", "{EC322E34-5012-43EE-B2D2-9F57A5F17289}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -129,6 +131,10 @@ Global
 		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E52BF2F4-6941-493F-8022-CD783889C1E2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EC322E34-5012-43EE-B2D2-9F57A5F17289}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EC322E34-5012-43EE-B2D2-9F57A5F17289}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EC322E34-5012-43EE-B2D2-9F57A5F17289}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{EC322E34-5012-43EE-B2D2-9F57A5F17289}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE